add maths and guides

Author: SupaHam

AGENTS.md

@@ -4,8 +4,9 @@ This file applies only to agents working in the `bebe/` repository.
 
 ## Repo Contract
 
-- `bebe` is the standalone framework repo for the `@blurengine/bebe` package, its source, tests, docs, and release surface.
-- The initial public surface is context-first. Do not widen exports without updating tests, package metadata, and README together.
+- `bebe` is the standalone game engine library repo for the `@blurengine/bebe` package, its source, tests, docs, and release surface.
+- The package root stays context-first. Additional public subpaths must be introduced intentionally and updated together with tests, package metadata, and README.
+- Use [docs/guides/engine-philosophy.md](d:/Users/supah/Documents/programming/go/src/gitlab.com/Blockception/personal/bebe/docs/guides/engine-philosophy.md) as the north-star design guide when evaluating new features, API shape, and architectural tradeoffs.
 - This file is for authoring `bebe` itself.
 
 ## Maintenance Rules
@@ -24,3 +25,17 @@ This file applies only to agents working in the `bebe/` repository.
 4. Treat `Context` as lifecycle and resource ownership infrastructure, not a dumping ground for unrelated feature state. New responsibilities should usually become services or standalone primitives before they become `Context` features.
 5. If Bedrock is missing an API and `bebe` fills the gap through polling or derived state, design that solution so consumers can reuse the same primitive to build their own higher-level features.
 6. When naming similar capabilities, prefer one vocabulary and one implementation path. Avoid sibling APIs that solve the same problem with slightly different names or behavior.
+7. In maths APIs, prefer the class types (`Vec2`, `Vec3`, `AABB`) as the primary authored surface. Keep raw structural helpers only for Bedrock interop, scalar queries, and low-allocation edge work; do not mirror the full class algebra in util helpers.
+8. Use named exported types instead of repeating anonymous structural shapes in public maths APIs when those shapes appear more than once.
+9. Plain utility names should be safe transforms for normal finite inputs. Use `parse...` for fallible conversion that returns `undefined`, and `assert...` for explicit validation that throws.
+10. Document exported types the same way you document exported functions. A public type should not force users to reverse-engineer intent from its shape alone.
+11. Public docs must describe important edge-case behavior and defensive fallbacks, not just the happy path. If a helper returns `undefined`, ignores invalid data, normalizes inputs, or falls back to a last-resort value, say so explicitly in the doc comment.
+12. Keep public documentation scan-first and behavior-first. `README.md` should stay concise and point readers at `docs/`, while longer guides should explain defaults, ownership, and non-obvious behavior instead of trying to mirror the source file symbol-for-symbol.
+13. Prefer human-readable notes over code-shaped prose in docs. When documenting a feature, explain what it owns, when it cleans up, what defaults matter, and which edge cases surprise users most.
+14. Document the code as it exists today. Avoid historical framing such as "used to", "no longer", or other changelog-style wording in feature guides unless the document is explicitly a migration or changelog document.
+15. Describe behavior directly. Do not explain a current contract by contrasting it with an internal implementation history or an alternative contract the user was never promised.
+16. Keep guide structure familiar across the repo. Prefer a shared flow such as `Purpose`, `Use It When`, `Core Model`, `Important Behaviours`, and `Choosing The Right API` unless a guide has a strong reason to differ.
+17. Keep `docs/README.md` reader-facing. Maintainer guidance, authoring rules, and agent instructions belong in `AGENTS.md` or contributor docs, not in the public docs index.
+18. Keep philosophy guides durable. They should express stable principles, tradeoffs, and anti-goals rather than current package layout, feature catalogs, or temporary implementation details.
+19. Use British English in reader-facing guides by default. Keep code identifiers, API names, and quoted external names unchanged unless there is a specific reason to adapt them.
+20. Use simple American English for code-facing writing by default. Prefer it for identifiers, API names, source comments, and code-adjacent doc comments so authored code stays predictable and easy to scan.

README.md

@@ -1,35 +1,52 @@
 # BlurEngine Bebe
 
-Standalone context and lifecycle utilities for Minecraft Bedrock scripting.
+Game engine library for Minecraft Bedrock scripting.
 
-## Package
+> Warning: `bebe` is still in an early stage of development. Backward compatibility is not guaranteed yet, and breaking changes may happen while the public engine surface is still being shaped.
 
-- `@blurengine/bebe`: context and lifecycle layer for Minecraft Bedrock scripting
+## Packages
+
+- `@blurengine/bebe`: engine lifecycle, ownership, and runtime primitives
+- `@blurengine/bebe/maths`: vectors, AABBs, tweens, and numeric helpers
 - `npm install @blurengine/bebe @minecraft/server`
-- exports: `@blurengine/bebe`
 
-## Usage
+## Quick Start
 
 ```ts
 import { Context } from "@blurengine/bebe";
+import { tweenNumber } from "@blurengine/bebe/maths";
 
 const ctx = new Context();
 
-ctx.timeout(20, () => {
-  // ...
+tweenNumber(ctx, {
+  from: 0,
+  to: 1,
+  durationTicks: 20,
+  onUpdate(value) {
+    console.warn(`progress: ${Math.round(value * 100)}%`);
+  },
 });
-
-ctx.dispose();
 ```
 
-## Docs
+## What Bebe Is For
+
+- Provide a game engine layer for Bedrock scripting that can own runtime work, compose features, and grow into higher-level engine systems over time.
+- Keep timers, subscriptions, spawned feature scopes, and other runtime work owned by one `Context`.
+- Provide a separate maths surface for vector, AABB, tween, and scalar helpers without making the root package feel overloaded.
 
+## Documentation
+
+- [Docs Index](./docs/README.md)
+- [Context Guide](./docs/guides/context.md)
+- [Maths Guide](./docs/guides/maths.md)
 - [Changelog](./CHANGELOG.md)
 
-## Local Development
+## Development
 
-- `npm install`
-- `npm run check`
+```bash
+npm install
+npm run check
+```
 
 ## License
 

docs/README.md

@@ -0,0 +1,28 @@
+# BlurEngine Bebe Docs
+
+These are the canonical guides for `@blurengine/bebe` and its public subpaths.
+
+## Guides
+
+- [Context Guide](./guides/context.md)
+- [Context Patterns](./guides/context-patterns.md)
+- [Maths Guide](./guides/maths.md)
+- [Engine Philosophy](./guides/engine-philosophy.md)
+- [Package Structure](./guides/package-structure.md)
+
+## Start Here
+
+- Start with the Context Guide if you are trying to understand ownership, cleanup, and feature lifetimes.
+- Read Context Patterns next if you want concrete ways to structure feature scopes and services.
+- Start with the Maths Guide if you are working with vectors, AABBs, tweens, or numeric helpers.
+- Read Engine Philosophy if you are deciding whether a new feature fits the current direction of `bebe`.
+- Read Package Structure if you are choosing imports or navigating the repo.
+
+## Scope
+
+These docs cover:
+
+- lifecycle ownership through `Context`
+- timers, subscriptions, child scopes, services, and tracked entities
+- the public maths surface under `@blurengine/bebe/maths`
+- defaults, edge cases, and behavior notes that matter when using `bebe` in Bedrock runtime code

docs/guides/context-patterns.md

@@ -0,0 +1,132 @@
+# Context Patterns
+
+## Purpose
+
+This guide shows the main ways to structure feature lifetimes with `Context`.
+
+Use it when you already understand what `Context` is, but you want a clearer sense of how many scopes to create, where services belong, and when `use(...)` is the right tool.
+
+## Use It When
+
+- a feature owns several timers, subscriptions, or tracked entities together
+- a feature needs shorter-lived nested work inside a larger lifetime
+- you are deciding between direct ownership, a child scope, a service, or explicit teardown
+- you want authored code to follow the same ownership shape across the repo
+
+## Core Model
+
+- one feature lifetime -> one `Context`
+- one shorter nested lifetime -> one child scope
+- one shared runtime helper -> one service on the scope that should own it
+- one custom teardown with no dedicated helper -> `use(...)`
+
+The goal is not to create more scopes for their own sake. The goal is to make ownership obvious.
+
+## Important Patterns
+
+### Feature Scope
+
+Use one `Context` for one feature lifetime.
+
+This is the default pattern for:
+
+- a temporary gameplay system
+- a feature session
+- one controller object that owns several runtime behaviours together
+
+Keep related work on that one context:
+
+- `subscribe(...)`
+- `timeout(...)`
+- `interval(...)`
+- `run(...)`
+- `trackEntity(...)`
+
+Dispose the context when the feature ends.
+
+### Child Scope
+
+Use `createScope(...)` when one part of a feature has a shorter lifetime than the parent feature.
+
+Good fits:
+
+- a temporary effect inside a longer-running system
+- one spawned entity inside a broader feature
+- one branch of logic that should stop without tearing down the whole parent
+
+The child scope should represent a real lifetime boundary. If it does not, keep the work on the parent context.
+
+### Subscription Ownership
+
+Use `subscribe(...)` when the work is event-driven and the subscription should end with the context.
+
+This is the normal pattern for Bedrock events:
+
+- register through `ctx.subscribe(...)`
+- keep the returned unsubscribe only when the feature may stop earlier than the context lifetime
+
+If the handler should only run a fixed number of times, use `subscribe({ source, n }, handler)`.
+
+### Service On A Parent Scope
+
+Use a service when several parts of the same feature tree need one shared runtime-owned helper.
+
+Good fits:
+
+- monitors
+- registries
+- caches tied to one feature lifetime
+- helper objects that own both state and behaviour
+
+Put the service on the scope that should own its lifetime.
+
+That usually means:
+
+- feature-wide helper -> parent scope service
+- local one-off helper -> local scope value, not a service
+
+### Entity Ownership
+
+Use `trackEntity(...)` when a context owns one or more entities.
+
+This is a good pattern when:
+
+- one feature scope owns several spawned entities that should be removed together
+- one scope exists because one specific entity exists
+- entities should be removed when the owning context is disposed
+- one tracked entity should also be able to end the context lifetime when it disappears
+
+Important defaults:
+
+- `removeOnDispose` defaults to `true`
+- `linkRemove` defaults to `false`
+
+The important distinction is:
+
+- `removeOnDispose` makes the context own entity cleanup
+- `linkRemove` lets a tracked entity act as a lifetime signal for the context
+
+One entity per scope is a useful pattern, but it is not the only intended use. A single context can own many related entities.
+
+### Explicit Teardown
+
+Use `use(...)` when the feature needs teardown that does not already map to a more specific helper.
+
+This is the lowest-level ownership primitive, so it should stay the exception, not the first thing every feature reaches for.
+
+Reach for it when:
+
+- you have custom teardown logic
+- the work is not a service, subscription, timer, or tracked entity
+- the more specific helpers would only wrap the same teardown less clearly
+
+## Choosing The Right Pattern
+
+- one feature lifetime -> `new Context()`
+- shorter nested lifetime -> `createScope(...)`
+- Bedrock event ownership -> `subscribe(...)`
+- shared runtime helper -> service
+- one or more owned entities -> `trackEntity(...)`
+- custom teardown -> `use(...)`
+
+If more than one pattern seems possible, prefer the one that makes lifetime ownership easiest to explain in one sentence.

docs/guides/context.md

@@ -0,0 +1,100 @@
+# Context Guide
+
+## Purpose
+
+`Context` is the lifecycle ownership layer in `bebe`.
+
+Use it when a feature creates runtime work that should be cleaned up through one ownership scope.
+
+## Use It When
+
+- a feature owns timers, subscriptions, or tracked entities
+- a piece of runtime behaviour needs clear cleanup boundaries
+- one feature needs shorter-lived child scopes inside a larger lifetime
+- shared runtime helpers should belong to one feature lifetime instead of floating globally
+
+## Core Model
+
+- Create a `Context` for a feature lifetime.
+- Register work on that context.
+- Create child scopes when part of that feature needs a shorter lifetime.
+- Dispose the parent when the feature ends.
+
+The central question is: which context owns this work?
+
+## What Context Owns
+
+A context can own:
+
+- `run`, `timeout`, and `interval` callbacks
+- event subscriptions created through `subscribe(...)`
+- child scopes created through `createScope(...)`
+- services stored through `setService(...)` and `ensureService(...)`
+- tracked entities registered through `trackEntity(...)`
+- explicit cleanup registered through `use(...)` or `onDispose(...)`
+
+## Important Behaviours
+
+### `new Context()`
+
+Directly constructed contexts join the internal root disposal tree.
+
+### `createScope(...)`
+
+Child scopes inherit service lookup from their parent by default. This is useful for feature-local scopes that need access to long-lived services. If a child should not see parent services, disable inheritance when you create the scope.
+
+### `run(...)`, `timeout(...)`, and `interval(...)`
+
+- `run(fn)` is the next-tick convenience form of `timeout(0, fn)`
+- negative tick values are clamped up to `0`
+- `interval({ ticks, n }, fn)` can auto-stop after `n` runs
+
+### `subscribe(...)`
+
+`subscribe(...)` returns an unsubscribe function and also registers that teardown with the owning context.
+
+- disposing the context unsubscribes automatically
+- `subscribe({ source, n }, handler)` auto-unsubscribes after `n` handler runs
+- the returned unsubscribe function is useful when a feature needs to stop earlier than the context lifetime
+
+### `onDispose(...)`
+
+`onDispose(...)` callbacks are scheduled through `system.run(...)` during disposal.
+
+That scheduling matters when teardown order is important.
+
+### Services
+
+Services are lifecycle-owned values stored on a context and looked up by key.
+
+They are a good fit for:
+
+- monitors
+- registries
+- caches tied to a runtime feature lifetime
+- helper objects that expose behaviour and state together
+
+Use services for runtime-owned helpers and shared feature infrastructure. Use ordinary locals for plain local state.
+
+### `trackEntity(...)`
+
+`trackEntity(...)` is useful when a context owns one or more spawned or long-lived entities.
+
+Behaviour to remember:
+
+- `removeOnDispose` defaults to `true`
+- `linkRemove` defaults to `false`
+- disposing the context attempts to remove every tracked entity owned by that context
+- `linkRemove: true` makes the context dispose itself when that tracked entity is removed
+
+## Choosing The Right API
+
+Most authored code should stay inside a small set of patterns:
+
+- feature lifetime -> `Context`
+- shorter nested lifetime -> `createScope(...)`
+- Bedrock event ownership -> `subscribe(...)`
+- shared runtime helper -> service
+- custom teardown with no dedicated helper -> `use(...)`
+
+`use(...)` is the lower-level ownership primitive. Reach for it when the more specific helpers do not match the work you need to own.