@antha/engine 0.0.1

package/LICENSE-CC0

@@ -0,0 +1,121 @@
+CC0 1.0 Universal
+
+Creative Commons Legal Code
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 electrovir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# Antha
+
+The Antha game engine (for the web), where everything is a mod! The only thing this engine core includes is a framework for flexibly defining and inserting mods with all the tools they need to be successful.
+
+-   Demo: https://electrovir.github.io/antha/demo
+
+## Install
+
+```sh
+npm i antha
+```

package/dist/antha-engine.d.ts

@@ -0,0 +1,312 @@
+import { type AnyObject, type Branded, type MaybePromise, type PartialWithUndefined, type RequiredAndNotNull } from '@augment-vir/common';
+import { type HtmlInterpolation } from 'element-vir';
+import { Observable } from 'observavir';
+import { type RequireExactlyOne } from 'type-fest';
+import { type AnthaLogger } from './logger/antha-logger.js';
+/**
+ * A string type used for mod instances. In reality these are just strings, but this branded type
+ * helps keep track of them. Under the hood, these are CUID2 ids.
+ *
+ * @category Internal
+ */
+export type ModInstanceId = Branded<string, 'antha-mod-instance-id'>;
+/**
+ * Parameters passed to the execute callback in {@link AnthaMod}.
+ *
+ * @category Internal
+ */
+export type ModExecuteParams<State extends AnyObject> = {
+    state: Partial<State>;
+    engine: AnthaEngine;
+    ticksSinceLastExecute: number;
+    msSinceLastExecute: DOMHighResTimeStamp;
+    lastExecution: Readonly<LastExecution> | undefined;
+    currentTick: number;
+    hostElement: HTMLElement;
+    modInstanceId: ModInstanceId;
+} & ModOptions;
+/**
+ * Parameters passed to the cleanup callback in {@link AnthaMod}.
+ *
+ * @category Internal
+ */
+export type ModCleanupParams<State extends AnyObject> = {
+    state: Partial<State>;
+    engine: AnthaEngine;
+    hostElement: HTMLElement;
+    modInstanceId: ModInstanceId;
+} & ModOptions;
+/**
+ * Return this from a mod's {@link AnthaMod.execute} callback to instruct {@link AnthaEngine} that the
+ * mod's current execution should not count toward the mod's frequency schedule. This is useful when
+ * a mod needs a dependency (such as a canvas or external resource) that isn't ready yet so that the
+ * engine will keep retrying on subsequent ticks, even if the mod has a low execution frequency.
+ *
+ * @category Mod
+ */
+export declare const SkipExecution: unique symbol;
+/**
+ * Type for {@link SkipExecution}.
+ *
+ * @category Mod
+ */
+export type SkipExecution = typeof SkipExecution;
+/**
+ * Allowed output from the execute callback in {@link AnthaMod}.
+ *
+ * @category Internal
+ */
+export type ModExecuteResult = MaybePromise<HtmlInterpolation | void | SkipExecution>;
+/**
+ * Possible options to use when defining {@link AnthaMod}.
+ *
+ * @category Internal
+ */
+export type ModOptions = {
+    /**
+     * The frequency at which this mod should execute.
+     *
+     * - `undefined`: execute on every tick
+     * - `duration`: execute on each duration. This will be converted to a tick count based on what
+     *   tick speed the engine is running at.
+     * - `ticks`: execute every `ticks` ticks.
+     *
+     * @default undefined
+     */
+    frequency: RequireExactlyOne<{
+        durationMs: number;
+        ticks: number;
+    }> | undefined;
+    /**
+     * If `true`, this mod will execute immediately on game engine init instead of waiting for its
+     * first tick to hit based on the given frequency configuration. If frequency is omitted or
+     * `undefined`, this option is not necessary.
+     *
+     * @default false
+     */
+    executeImmediately: boolean;
+};
+/**
+ * A mod for {@link AnthaEngine}. This is the core of getting anything done in the engine, everything
+ * runs in a mod.
+ *
+ * @category Mod
+ * @example
+ *
+ * ```ts
+ * import {AnthaMod} from '@antha/engine';
+ * import {html} from 'element-vir';
+ *
+ * const myMod: AnthaMod<{count: number}> = {
+ *     execute({state}) {
+ *         state.count = (state.count || 0) + 1;
+ *         return html`
+ *             <span class="counter">${String(state.count)}</span>
+ *         `;
+ *     },
+ * };
+ * ```
+ */
+export type AnthaMod<State extends AnyObject = any> = {
+    /**
+     * Not used by the Antha engine, just a nice string to help debugging so you can which mod is
+     * which.
+     */
+    modName: string;
+    /**
+     * The execute callback. This is where the mod's functionality lives. This will be called in
+     * each tick based on the provided frequency. Any non-nullish output will be rendered as HTML to
+     * the DOM.
+     */
+    execute: (this: void, params: Readonly<ModExecuteParams<NoInfer<State>>>) => ModExecuteResult;
+} & PartialWithUndefined<{
+    initState: Partial<NoInfer<State>>;
+    /**
+     * Use this to cleanup resources that the mod has created. This is called when the engine is
+     * reset.
+     */
+    cleanup: (this: void, params: Readonly<ModCleanupParams<NoInfer<State>>>) => MaybePromise<void>;
+} & ModOptions>;
+/**
+ * Extracts state type from a mod.
+ *
+ * @category Internal
+ */
+export type AnthaModeState<Mod extends AnthaMod> = Mod extends AnthaMod<infer State> ? State : never;
+/**
+ * A helper for defining {@link AnthaMod} inline. This is _not_ required in order to define an
+ * {@link AnthaMod}. It simply helps with type inference.
+ *
+ * @category Mod
+ * @example
+ *
+ * ```ts
+ * import {defineAnthaMod} from '@antha/engine';
+ * import {html} from 'element-vir';
+ *
+ * defineAnthaMod<{count: number}>({
+ *     execute({state}) {
+ *         state.count = (state.count || 0) + 1;
+ *         return html`
+ *             <span class="counter">${String(state.count)}</span>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare function defineAnthaMod<State extends AnyObject = never>(mod: AnthaMod<NoInfer<State>>): AnthaMod<NoInfer<State>>;
+/**
+ * Possible options to use when constructing {@link AnthaEngine}. Defaults are contained in
+ * {@link defaultAnthaEngineOptions}.
+ *
+ * @category Engine
+ */
+export type AnthaEngineOptions = PartialWithUndefined<{
+    /**
+     * A custom logger to handle mod and engine logs. By default, this merely logs to the browser
+     * console.
+     */
+    logger: AnthaLogger;
+}>;
+/**
+ * Default values for {@link AnthaEngineOptions}.
+ *
+ * @category Internal
+ */
+export declare const defaultAnthaEngineOptions: RequiredAndNotNull<AnthaEngineOptions>;
+/**
+ * The last known execution for a given mod. Passed to each mod's execute callback via
+ * {@link ModExecuteParams} and used inside {@link AnthaEngine} to keep track of when a mod should run
+ * again.
+ *
+ * @category Internal
+ */
+export type LastExecution = {
+    tick: number;
+    timeMs: DOMHighResTimeStamp;
+};
+/**
+ * Init options for the constructor of {@link AnthaEngine}.
+ *
+ * @category Internal
+ */
+export type AnthaEngineInit<State extends AnyObject = AnyObject> = PartialWithUndefined<{
+    /** The Antha mods to start the Antha engine with. */
+    mods: AnthaMod[];
+    /**
+     * Various options to start the Antha engine with.
+     *
+     * @default defaultAnthaEngineOptions
+     */
+    engineOptions: Readonly<AnthaEngineOptions>;
+    /**
+     * The host element to start the Antha engine with.
+     *
+     * @default globalThis.document.documentElement
+     */
+    hostElement: HTMLElement;
+    initState: Partial<State>;
+}>;
+/**
+ * The Antha Engine. This keeps track of when to execute each mod, the mod's template outputs, and
+ * the state passed to and mutated by each mod.
+ *
+ * @category Engine
+ * @example
+ *
+ * ```ts
+ * import {AnthaEngine, defineAnthaMod} from '@antha/engine';
+ * import {html} from 'element-vir';
+ *
+ * new AnthaEngine({
+ *     mods: [
+ *         defineAnthaMod<{count: number}>({
+ *             execute({state}) {
+ *                 state.count = (state.count || 0) + 1;
+ *                 return html`
+ *                     <span class="counter">${String(state.count)}</span>
+ *                 `;
+ *             },
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
+export declare class AnthaEngine<State extends AnyObject = AnyObject> {
+    constructor(init?: AnthaEngineInit<State> | undefined);
+    /**
+     * Send a log through the engine. This will use the user's provided logger or default to browser
+     * logs.
+     */
+    log: AnthaLogger;
+    /** Get this.hostElement but if one doesn't exist yet, create one. */
+    protected getEnsuredHostElement(): HTMLElement;
+    /** The element that this engine considers itself to be "hosted" in. */
+    hostElement: HTMLElement | undefined;
+    /**
+     * Hook into this observable for updating event-based code, like UI elements. This is used
+     * directly in AnthaUi to update the UI.
+     */
+    readonly observable: Observable<HtmlInterpolation[]>;
+    /** The current engine options. This can be modified at any time. */
+    readonly options: RequiredAndNotNull<AnthaEngineOptions>;
+    /** The current mods to execute. This can be modified at any time. */
+    readonly currentMods: AnthaMod[];
+    /**
+     * Used to store each template by its mod so that mod-to-template tracking remains stable even
+     * if mods are inserted, removed, or moved around in the `currentMods` array.
+     */
+    readonly currentTemplateMap: WeakMap<AnthaMod<any>, HtmlInterpolation>;
+    readonly modInstanceIdMap: WeakMap<AnthaMod<any>, ModInstanceId>;
+    /**
+     * The current array of templates. This array is mutated and passed to the UI via the
+     * `observable`.
+     */
+    readonly currentTemplateArray: HtmlInterpolation[];
+    /**
+     * Used to store when each mod was last executed in order to know when the next execution should
+     * be.
+     */
+    readonly lastModExecution: WeakMap<AnthaMod<any>, Readonly<LastExecution>>;
+    /** The engine's current tick number. This is incremented after each tick is finished executing. */
+    currentTick: number;
+    /**
+     * The engine's current state. This is intended to be mutated by mods, but it can also be
+     * modified at any time externally.
+     */
+    readonly state: Partial<State>;
+    /** Total milliseconds elapsed since the engine started. Updated each tick. */
+    totalMs: DOMHighResTimeStamp;
+    /** When the engine started running its loop. */
+    engineStartTime: DOMHighResTimeStamp;
+    /**
+     * Indicates whether the loop is running or not. This can be freely modified at any time to
+     * start or stop the next tick.
+     */
+    isLoopRunning: boolean;
+    /** Indicates whether a tick is currently running or not. This should not be modified externally. */
+    readonly isTickRunning: boolean;
+    /**
+     * Stop the tick loop. If the loop already isn't running, no changes will be made.
+     *
+     * @returns Whether the loop was stopped or not.
+     */
+    stopLoop(): boolean;
+    /** Reset the engine back to its initial state and run all mod cleanup callbacks. */
+    reset(): Promise<void>;
+    /**
+     * Start the tick loop. If the loop is already running, no changes will be made.
+     *
+     * @returns Whether the loop was started or not.
+     */
+    startLoop(): boolean;
+    /** Execute a single tick on each render frame. */
+    protected runTickInLoop(): Promise<void>;
+    /**
+     * Run a single tick. This happens automatically in a loop if `startLoop` is called or
+     * `isLoopRunning` is set to `true`.
+     */
+    runSingleTick(): Promise<void>;
+    /** Used to determine if a mod should execute right now or not. */
+    shouldModExecute(mod: Readonly<AnthaMod>, lastExecution: Readonly<LastExecution> | undefined): boolean;
+}

package/dist/antha-engine.js

@@ -0,0 +1,297 @@
+import { waitUntil } from '@augment-vir/assert';
+import { applyBrand, awaitedForEach, getOrSetFromMap, makeWritable, mergeDefinedProperties, } from '@augment-vir/common';
+import { createId } from '@paralleldrive/cuid2';
+import { css, html } from 'element-vir';
+import { Observable } from 'observavir';
+import { AnthaUi } from './antha-ui.element.js';
+import { browserAnthaLogger } from './logger/browser-antha-logger.js';
+/**
+ * Return this from a mod's {@link AnthaMod.execute} callback to instruct {@link AnthaEngine} that the
+ * mod's current execution should not count toward the mod's frequency schedule. This is useful when
+ * a mod needs a dependency (such as a canvas or external resource) that isn't ready yet so that the
+ * engine will keep retrying on subsequent ticks, even if the mod has a low execution frequency.
+ *
+ * @category Mod
+ */
+export const SkipExecution = Symbol.for('antha-engine-mode-skip-execution');
+/**
+ * A helper for defining {@link AnthaMod} inline. This is _not_ required in order to define an
+ * {@link AnthaMod}. It simply helps with type inference.
+ *
+ * @category Mod
+ * @example
+ *
+ * ```ts
+ * import {defineAnthaMod} from '@antha/engine';
+ * import {html} from 'element-vir';
+ *
+ * defineAnthaMod<{count: number}>({
+ *     execute({state}) {
+ *         state.count = (state.count || 0) + 1;
+ *         return html`
+ *             <span class="counter">${String(state.count)}</span>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export function defineAnthaMod(mod) {
+    return mod;
+}
+/**
+ * Default values for {@link AnthaEngineOptions}.
+ *
+ * @category Internal
+ */
+export const defaultAnthaEngineOptions = {
+    logger: browserAnthaLogger,
+};
+/**
+ * The Antha Engine. This keeps track of when to execute each mod, the mod's template outputs, and
+ * the state passed to and mutated by each mod.
+ *
+ * @category Engine
+ * @example
+ *
+ * ```ts
+ * import {AnthaEngine, defineAnthaMod} from '@antha/engine';
+ * import {html} from 'element-vir';
+ *
+ * new AnthaEngine({
+ *     mods: [
+ *         defineAnthaMod<{count: number}>({
+ *             execute({state}) {
+ *                 state.count = (state.count || 0) + 1;
+ *                 return html`
+ *                     <span class="counter">${String(state.count)}</span>
+ *                 `;
+ *             },
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
+export class AnthaEngine {
+    constructor(init) {
+        this.state = init?.initState || {};
+        this.options = mergeDefinedProperties(defaultAnthaEngineOptions, init?.engineOptions);
+        this.currentMods = init?.mods || [];
+        this.hostElement = init?.hostElement;
+        this.log = this.options.logger;
+    }
+    /**
+     * Send a log through the engine. This will use the user's provided logger or default to browser
+     * logs.
+     */
+    log;
+    /** Get this.hostElement but if one doesn't exist yet, create one. */
+    getEnsuredHostElement() {
+        if (!this.hostElement) {
+            const instance = globalThis.document.createElement(AnthaUi.tagName);
+            this.hostElement = instance;
+            instance.assignInputs({
+                engine: this,
+                options: {
+                    disableConnectStart: true,
+                    disableDisconnectReset: true,
+                },
+            });
+            globalThis.document.body.append(instance);
+        }
+        return this.hostElement;
+    }
+    /** The element that this engine considers itself to be "hosted" in. */
+    hostElement;
+    /**
+     * Hook into this observable for updating event-based code, like UI elements. This is used
+     * directly in AnthaUi to update the UI.
+     */
+    observable = new Observable({
+        defaultValue: [],
+        equalityCheck: undefined,
+    });
+    /** The current engine options. This can be modified at any time. */
+    options;
+    /** The current mods to execute. This can be modified at any time. */
+    currentMods;
+    /**
+     * Used to store each template by its mod so that mod-to-template tracking remains stable even
+     * if mods are inserted, removed, or moved around in the `currentMods` array.
+     */
+    currentTemplateMap = new WeakMap();
+    modInstanceIdMap = new WeakMap();
+    /**
+     * The current array of templates. This array is mutated and passed to the UI via the
+     * `observable`.
+     */
+    currentTemplateArray = [];
+    /**
+     * Used to store when each mod was last executed in order to know when the next execution should
+     * be.
+     */
+    lastModExecution = new WeakMap();
+    /** The engine's current tick number. This is incremented after each tick is finished executing. */
+    currentTick = 0;
+    /**
+     * The engine's current state. This is intended to be mutated by mods, but it can also be
+     * modified at any time externally.
+     */
+    state;
+    /** Total milliseconds elapsed since the engine started. Updated each tick. */
+    totalMs = 0;
+    /** When the engine started running its loop. */
+    engineStartTime = performance.now();
+    /**
+     * Indicates whether the loop is running or not. This can be freely modified at any time to
+     * start or stop the next tick.
+     */
+    isLoopRunning = false;
+    /** Indicates whether a tick is currently running or not. This should not be modified externally. */
+    isTickRunning = false;
+    /**
+     * Stop the tick loop. If the loop already isn't running, no changes will be made.
+     *
+     * @returns Whether the loop was stopped or not.
+     */
+    stopLoop() {
+        if (this.isLoopRunning) {
+            this.isLoopRunning = false;
+            return true;
+        }
+        else {
+            return false;
+        }
+    }
+    /** Reset the engine back to its initial state and run all mod cleanup callbacks. */
+    async reset() {
+        this.stopLoop();
+        await waitUntil.isFalse(() => this.isTickRunning);
+        this.currentTick = 0;
+        /** Clear all per-mod tracking for current mods. */
+        await awaitedForEach(this.currentMods, async (mod) => {
+            this.lastModExecution.delete(mod);
+            this.currentTemplateMap.delete(mod);
+            await mod.cleanup?.({
+                engine: this,
+                hostElement: this.getEnsuredHostElement(),
+                modInstanceId: getOrSetFromMap(this.modInstanceIdMap, mod, () => applyBrand(createId())),
+                state: this.state,
+                executeImmediately: mod.executeImmediately || false,
+                frequency: mod.frequency || undefined,
+            });
+        });
+        this.currentTemplateArray.length = 0;
+        /** Clear all state properties. */
+        Object.keys(this.state).forEach((key) => {
+            delete this.state[key];
+        });
+        this.observable.setValue([]);
+    }
+    /**
+     * Start the tick loop. If the loop is already running, no changes will be made.
+     *
+     * @returns Whether the loop was started or not.
+     */
+    startLoop() {
+        if (this.isLoopRunning) {
+            return false;
+        }
+        this.engineStartTime = performance.now();
+        this.isLoopRunning = true;
+        void this.runTickInLoop();
+        return true;
+    }
+    /** Execute a single tick on each render frame. */
+    async runTickInLoop() {
+        if (!this.isLoopRunning) {
+            return;
+        }
+        await this.runSingleTick();
+        requestAnimationFrame(() => this.runTickInLoop());
+    }
+    /**
+     * Run a single tick. This happens automatically in a loop if `startLoop` is called or
+     * `isLoopRunning` is set to `true`.
+     */
+    async runSingleTick() {
+        makeWritable(this).isTickRunning = true;
+        /** Clear the array as we're about to populate it. */
+        this.currentTemplateArray.length = 0;
+        const executionStart = performance.now();
+        this.totalMs = executionStart - this.engineStartTime;
+        /**
+         * Use a plain `for` loop instead of `awaitedForEach` so that synchronous mods execute
+         * without microtask boundaries between them. Only yield when a mod actually returns a
+         * `Promise`.
+         */
+        for (let index = 0; index < this.currentMods.length; index++) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const mod = this.currentMods[index];
+            const lastExecution = this.lastModExecution.get(mod);
+            const shouldExecute = this.shouldModExecute(mod, lastExecution);
+            let executeResult;
+            if (shouldExecute) {
+                if (!lastExecution && mod.initState) {
+                    Object.assign(this.state, mod.initState);
+                }
+                const rawResult = mod.execute({
+                    engine: this,
+                    modInstanceId: getOrSetFromMap(this.modInstanceIdMap, mod, () => applyBrand(createId())),
+                    currentTick: this.currentTick,
+                    state: this.state,
+                    ticksSinceLastExecute: this.currentTick - (lastExecution?.tick ?? 0),
+                    executeImmediately: mod.executeImmediately || false,
+                    frequency: mod.frequency || undefined,
+                    lastExecution,
+                    hostElement: this.getEnsuredHostElement(),
+                    msSinceLastExecute: executionStart - (lastExecution?.timeMs ?? this.engineStartTime),
+                });
+                executeResult = rawResult instanceof Promise ? await rawResult : rawResult;
+            }
+            const skipped = executeResult === SkipExecution;
+            const rawTemplate = shouldExecute && !skipped
+                ? executeResult || undefined
+                : undefined;
+            const modTemplate = shouldExecute && !skipped
+                ? rawTemplate
+                    ? html `
+                              <div
+                                  data-antha-mod=${mod.modName}
+                                  style=${css `
+                                      display: contents;
+                                  `}
+                              >
+                                  ${rawTemplate}
+                              </div>
+                          `
+                    : undefined
+                : this.currentTemplateMap.get(mod);
+            this.currentTemplateArray[index] = modTemplate;
+            if (shouldExecute && !skipped) {
+                this.currentTemplateMap.set(mod, modTemplate);
+                this.lastModExecution.set(mod, {
+                    tick: this.currentTick,
+                    timeMs: executionStart,
+                });
+            }
+        }
+        this.currentTick++;
+        this.observable.setValue(this.currentTemplateArray);
+        makeWritable(this).isTickRunning = false;
+    }
+    /** Used to determine if a mod should execute right now or not. */
+    shouldModExecute(mod, lastExecution) {
+        if (!mod.frequency || (!lastExecution && mod.executeImmediately)) {
+            return true;
+        }
+        else if (mod.frequency.ticks) {
+            const ticksSinceLastExecution = this.currentTick - (lastExecution?.tick || 0);
+            return ticksSinceLastExecution >= mod.frequency.ticks;
+        }
+        else if (mod.frequency.durationMs) {
+            const msSinceLastExecution = performance.now() - (lastExecution?.timeMs || 0);
+            return msSinceLastExecution >= mod.frequency.durationMs;
+        }
+        return true;
+    }
+}

package/dist/antha-ui.element.d.ts

@@ -0,0 +1,41 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type AnthaEngine } from './antha-engine.js';
+/**
+ * Options for {@link AnthaUi}.
+ *
+ * @category UI
+ */
+export type AnthaUiOptions = {
+    /**
+     * If set to `true`, the engine won't automatically be cleaned up when the {@link AnthaUi}
+     * element is disconnected or destroyed.
+     *
+     * @default false
+     */
+    disableDisconnectReset: boolean;
+    /**
+     * If set to `true`, the engine won't automatically be started up when the {@link AnthaUi}
+     * element is connected.
+     *
+     * @default false
+     */
+    disableConnectStart: boolean;
+};
+/**
+ * A built-in element for easily rendering {@link AnthaEngine} templates to the browser.
+ *
+ * @category UI
+ * @example
+ *
+ * ```ts
+ * import {AnthaUi, AnthaEngine} from '@antha/engine';
+ *
+ * const engine = new AnthaEngine();
+ * ```
+ */
+export declare const AnthaUi: import("element-vir").DeclarativeElementDefinition<"antha-ui", PartialWithUndefined<{
+    engine: AnthaEngine;
+    options: Readonly<PartialWithUndefined<AnthaUiOptions>>;
+}>, {
+    engineObservable: undefined | AnthaEngine["observable"];
+}, {}, "antha-ui-", "antha-ui-", readonly [], readonly []>;

package/dist/antha-ui.element.js

@@ -0,0 +1,68 @@
+import { css, defineElement, nothing } from 'element-vir';
+/**
+ * A built-in element for easily rendering {@link AnthaEngine} templates to the browser.
+ *
+ * @category UI
+ * @example
+ *
+ * ```ts
+ * import {AnthaUi, AnthaEngine} from '@antha/engine';
+ *
+ * const engine = new AnthaEngine();
+ * ```
+ */
+export const AnthaUi = defineElement()({
+    tagName: 'antha-ui',
+    styles: css `
+        :host {
+            /* Because all of these styles are defined on the host, you can easily override them. */
+            display: flex;
+            flex-direction: column;
+            align-items: flex-start;
+            height: 100dvh;
+            gap: 16px;
+            width: 100dvw;
+            box-sizing: border-box;
+            padding: 32px;
+            font-family: sans-serif;
+        }
+    `,
+    state() {
+        return {
+            engineObservable: undefined,
+        };
+    },
+    cleanup({ inputs, updateState }) {
+        if (!inputs.options?.disableDisconnectReset) {
+            void inputs.engine?.reset();
+        }
+        updateState({
+            /** Remove the observable on cleanup to stop render updates. */
+            engineObservable: undefined,
+        });
+    },
+    render({ state, updateState, inputs, host }) {
+        if (!inputs.engine) {
+            return nothing;
+        }
+        if (inputs.engine.hostElement !== host &&
+            (!inputs.engine.hostElement ||
+                inputs.engine.hostElement === globalThis.document.documentElement)) {
+            /**
+             * Automatically attach this element's host to the engine's host element if one has not
+             * been specifically set already.
+             */
+            inputs.engine.hostElement = host;
+        }
+        if (state.engineObservable !== inputs.engine.observable) {
+            /** Automatically swap out the observable if the engine changes. */
+            updateState({
+                engineObservable: inputs.engine.observable,
+            });
+            if (!inputs.options?.disableConnectStart) {
+                inputs.engine.startLoop();
+            }
+        }
+        return state.engineObservable?.value;
+    },
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './antha-engine.js';
+export * from './antha-ui.element.js';
+export * from './logger/antha-logger.js';
+export * from './logger/browser-antha-logger.js';
+export * from './logger/empty-antha-logger.js';
+export * from './logger/sentry-antha-logger.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './antha-engine.js';
+export * from './antha-ui.element.js';
+export * from './logger/antha-logger.js';
+export * from './logger/browser-antha-logger.js';
+export * from './logger/empty-antha-logger.js';
+export * from './logger/sentry-antha-logger.js';

package/dist/logger/antha-logger.d.ts

@@ -0,0 +1,30 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type EventExtraContext, type EventTags } from 'sentry-vir';
+/**
+ * Base logger methods.
+ *
+ * @category Internal
+ */
+export type BaseAnthaLogger = {
+    error: AnthaLog;
+    info: AnthaLog;
+    warning: AnthaLog;
+};
+/**
+ * The customizable logger used by Antha engine and its pre-built mods.
+ *
+ * @category Logger
+ */
+export type AnthaLogger = BaseAnthaLogger & {
+    /** Only logs if the given condition is true. */
+    if: (condition: boolean) => BaseAnthaLogger;
+};
+/**
+ * An individual log method.
+ *
+ * @category Internal
+ */
+export type AnthaLog = (this: void, message: string | Error, context?: PartialWithUndefined<{
+    context: EventExtraContext;
+    tags: EventTags;
+}> | undefined) => void;

package/dist/logger/antha-logger.js

@@ -0,0 +1 @@
+export {};

package/dist/logger/browser-antha-logger.d.ts

@@ -0,0 +1,8 @@
+import { type AnthaLogger } from './antha-logger.js';
+/**
+ * A pre-built {@link AnthaLogger} that simply logs everything to the browser's console. This is the
+ * default logger in `AnthaEngine`.
+ *
+ * @category Logger
+ */
+export declare const browserAnthaLogger: AnthaLogger;

package/dist/logger/browser-antha-logger.js

@@ -0,0 +1,29 @@
+import { baseEmptyAnthaLogger } from './empty-antha-logger.js';
+const baseBrowserAnthaLogger = {
+    error(message, context) {
+        console.error(message, context);
+    },
+    info(message, context) {
+        console.info(message, context);
+    },
+    warning(message, context) {
+        console.warn(message, context);
+    },
+};
+/**
+ * A pre-built {@link AnthaLogger} that simply logs everything to the browser's console. This is the
+ * default logger in `AnthaEngine`.
+ *
+ * @category Logger
+ */
+export const browserAnthaLogger = {
+    ...baseBrowserAnthaLogger,
+    if(condition) {
+        if (condition) {
+            return baseBrowserAnthaLogger;
+        }
+        else {
+            return baseEmptyAnthaLogger;
+        }
+    },
+};

package/dist/logger/empty-antha-logger.d.ts

@@ -0,0 +1,14 @@
+import { type AnthaLogger, type BaseAnthaLogger } from './antha-logger.js';
+/**
+ * Base log methods of {@link emptyAnthaLogger}.
+ *
+ * @category Internal
+ */
+export declare const baseEmptyAnthaLogger: BaseAnthaLogger;
+/**
+ * A pre-built {@link AnthaLogger} that simply logs everything to the browser's console. This is the
+ * default logger in `AnthaEngine`.
+ *
+ * @category Logger
+ */
+export declare const emptyAnthaLogger: AnthaLogger;

package/dist/logger/empty-antha-logger.js

@@ -0,0 +1,22 @@
+/**
+ * Base log methods of {@link emptyAnthaLogger}.
+ *
+ * @category Internal
+ */
+export const baseEmptyAnthaLogger = {
+    error() { },
+    info() { },
+    warning() { },
+};
+/**
+ * A pre-built {@link AnthaLogger} that simply logs everything to the browser's console. This is the
+ * default logger in `AnthaEngine`.
+ *
+ * @category Logger
+ */
+export const emptyAnthaLogger = {
+    ...baseEmptyAnthaLogger,
+    if() {
+        return baseEmptyAnthaLogger;
+    },
+};

package/dist/logger/sentry-antha-logger.d.ts

@@ -0,0 +1,8 @@
+import { type AnthaLogger } from './antha-logger.js';
+/**
+ * A pre-built {@link AnthaLogger} that sends logs to Sentry. Note that `initSentry` from
+ * `sentry-vir` must be called elsewhere for these logs to actually make it to sentry.
+ *
+ * @category Logger
+ */
+export declare const sentryAnthaLogger: AnthaLogger;

package/dist/logger/sentry-antha-logger.js

@@ -0,0 +1,30 @@
+import { handleError, sendLog } from 'sentry-vir';
+import { baseEmptyAnthaLogger } from './empty-antha-logger.js';
+const baseSentryAnthaLogger = {
+    error(message, context) {
+        handleError(message, context);
+    },
+    info(message, context) {
+        sendLog.info(message, context);
+    },
+    warning(message, context) {
+        sendLog.warning(message, context);
+    },
+};
+/**
+ * A pre-built {@link AnthaLogger} that sends logs to Sentry. Note that `initSentry` from
+ * `sentry-vir` must be called elsewhere for these logs to actually make it to sentry.
+ *
+ * @category Logger
+ */
+export const sentryAnthaLogger = {
+    ...baseSentryAnthaLogger,
+    if(condition) {
+        if (condition) {
+            return baseSentryAnthaLogger;
+        }
+        else {
+            return baseEmptyAnthaLogger;
+        }
+    },
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+    "name": "@antha/engine",
+    "version": "0.0.1",
+    "description": "The Antha game engine (for the web).",
+    "keywords": [
+        "vir",
+        "antha"
+    ],
+    "homepage": "https://github.com/electrovir/antha",
+    "bugs": {
+        "url": "https://github.com/electrovir/antha/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/electrovir/antha.git"
+    },
+    "license": "(MIT OR CC0-1.0)",
+    "author": {
+        "name": "electrovir",
+        "url": "https://github.com/electrovir"
+    },
+    "sideEffects": false,
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "virmator frontend build",
+        "compile": "virmator compile",
+        "docs": "virmator docs",
+        "start": "virmator frontend",
+        "test": "virmator test web",
+        "test:coverage": "npm run test coverage",
+        "test:docs": "virmator docs check",
+        "test:update": "npm test update"
+    },
+    "dependencies": {
+        "@augment-vir/assert": "^31.73.1",
+        "@augment-vir/common": "^31.73.1",
+        "@paralleldrive/cuid2": "^3.3.0",
+        "date-vir": "^8.5.0",
+        "observavir": "^2.3.2",
+        "sentry-vir": "^4.4.0",
+        "type-fest": "^5.7.0"
+    },
+    "devDependencies": {
+        "@augment-vir/test": "^31.73.1",
+        "@augment-vir/web": "^31.73.1",
+        "@web/dev-server-esbuild": "^1.0.5",
+        "@web/test-runner": "^0.20.2",
+        "@web/test-runner-commands": "^0.9.0",
+        "@web/test-runner-playwright": "^0.11.1",
+        "@web/test-runner-visual-regression": "^0.10.0",
+        "istanbul-smart-text-reporter": "^1.1.5",
+        "markdown-code-example-inserter": "^3.0.5",
+        "typedoc": "^0.28.19",
+        "typescript": "^6.0.3",
+        "vite": "^8.0.16"
+    },
+    "peerDependencies": {
+        "element-vir": ">=26"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}