kaplay-ui 1.0.0-alpha.13 → 1.0.0-alpha.14

package/README.md

@@ -17,6 +17,19 @@ For now it helps you build Game Objects like text buttons and labels — without
 
 ---
 
+## ✨ _What this plugin currently provides_
+
+When installed, this plugin extends the KAPLAY context (`k`) with:
+
+- `k.addTextButton()` – interactive buttons with centered text
+- `k.addLabel()` – lightweight, non-interactive text labels
+
+Each helper returns a regular KAPLAY game object enhanced with
+**convenience methods** for changing size, position, colors, text, and more
+after creation.
+
+---
+
 ## 📦 Installation
 
 ### Prerelease (new v1 work)
@@ -29,11 +42,9 @@ This gives you the latest `1.0.0‑alpha.*` builds.
 
 ---
 
-## 🚀 Usage (_1.0.0-alpha.\*_)
+## 🚀 Quick start (_1.0.0-alpha.\*_)
 
-**Kaplay UI** exports a plugin for adding UI Game Objects.
-
-The `kaplayUI` plugin is exported from the package root:
+The **Kaplay-UI** plugin is exported as `kaplayUI` from the package root:
 
 ```ts
 import kaplay from "kaplay";
@@ -47,130 +58,144 @@ const k = kaplay({
 You now have access to the UI helpers via your `k` instance:
 
 ```ts
-const btn = k.addTextButton("Play");
-const label = k.addLabel("Score: 0");
+const btn = k.addTextButton("Start");
+btn.onClick(() => {
+  k.go("game");
+});
+
+const lbl = k.addLabel("Score: 0");
+lbl.setLabelText("Score: 1");
 ```
 
 ---
 
 ## 🧩 Game Objects (_**1.0.0‑alpha.\***_)
 
-### 🔤 **Text Button** (`addTextButton()`)
-
-Creates a button-like GameObj with centered text and some convenient defaults.
+### 🔤 Text Button — `addTextButton()`
 
-#### _**Signature**_
+Creates a clickable button with centered text and default visuals.
 
 ```ts
-addTextButton(
-  txt: string,
-  opts?: object
-): GameObj
+const btn = k.addTextButton("Start", {
+  width: 200,
+  height: 80,
+});
 ```
 
-#### _**Default `opts` parameter values**_
+Buttons support runtime updates such as:
 
-| Parameter | Default |
-| --------- | :------ |
-| `width`   | `200`   |
-| `height`  | `100`   |
-| `radius`  | `10`    |
-| `posX`    | `0`     |
-| `posY`    | `0`     |
-| `outline` | `3`     |
-| `txtSize` | `22`    |
+```ts
+btn.setSize(300, 100);
+btn.setButtonColor([255, 120, 120]);
+btn.setButtonText("Go!");
+btn.setButtonTextSize(24);
+```
 
-#### _**Default styling**_
+Perfect for menus, dialogs, and in‑game actions.
+
+---
 
-| Comps                  | Values          |
-| ---------------------- | :-------------- |
-| `button anchor`        | `"topleft"`     |
-| `button color`         | `200, 200, 200` |
-| `button outline color` | `92, 91, 91`    |
-| `text anchor`          | `"center"`      |
-| `text color`           | `0, 0, 0`       |
+### 🏷️ Label — `addLabel()`
 
-#### _**Examples**_
+Creates a lightweight background + text container for HUD elements or titles.
 
 ```ts
-// Basic button
-const btn1 = k.addTextButton("Play!");
+const label = k.addLabel("Score: 0");
+```
 
-// Custom button
-const btn2 = k.addTextButton("Play!", { posX: 300, posY: 200 });
+Update it dynamically:
 
-// Add interactivity
-btn2.onClick(() => {
-  console.log("Button clicked!");
-});
+```ts
+label.setLabelText("Score: 10");
+label.setLabelTextColor([255, 255, 0]);
+label.setOpacity(0.9);
 ```
 
+Ideal for HUDs, counters, status text, and overlays.
+
 ---
 
-### 🏷️ **Label** (`addLabel()`)
+## 🎨 Customization
 
-A lightweight text-based UI element — ideal for HUD counters, tooltips, status text, or titles.
+kaplay-ui is designed to be **customized imperatively**, without hiding
+or abstracting away KAPLAY’s core APIs.
 
-#### _**Signature**_
+### ✅ Option-based customization (at creation)
+
+Both helpers accept an optional `opts` object for common configuration:
 
 ```ts
-addLabel(
-    txt: string,
-    opts?: object
-)
+const btn = k.addTextButton("Options", {
+  width: 250,
+  height: 70,
+  posX: 100,
+  posY: 200,
+  radius: 8,
+});
 ```
 
-#### _**Default `opts` values**_
+---
 
-| Parameter | Default |
-| --------- | ------- |
-| `width`   | `160`   |
-| `height`  | `96`    |
-| `txtSize` | `22`    |
+### ✅ Runtime customization (after creation)
 
-#### _**Default styling**_
+Each UI element exposes helper methods for updating its appearance and layout:
 
-| Comps           | Values          |
-| --------------- | :-------------- |
-| `label pos`     | `0, 0`          |
-| `label color`   | `0, 0,0 `       |
-| `label opacity` | `0.7`           |
-| `label anchor`  | `"topleft"`     |
-| `text color`    | `255, 255, 255` |
-| `text anchor`   | `"center"`      |
+```ts
+btn.setPosition(150, 220);
+btn.setButtonColor([80, 160, 255]);
+btn.setButtonTextColor([255, 255, 255]);
+```
 
-#### _**Examples**_
+This makes it easy to animate, react to state changes, or reuse UI elements.
 
-```ts
-// Basic label
-const lbl2 = k.addLabel("Score: 0");
+---
 
-// Custom label
-const lbl3 = k.addLabel("Start", { width: 100, height: 50 });
+### ✅ Full KAPLAY access
 
-// Update label text example
-let score = 0;
-const scoreLabel = k.addLabel(`Score: ${score}`);
+UI elements are **regular KAPLAY game objects**, so you can still use all
+standard KAPLAY features:
 
-k.wait(2, () => {
-  score++;
-  scoreLabel.children[0].text = `Score: ${score}`;
-});
+```ts
+btn.use(k.opacity(0.8));
+btn.onHover(() => btn.setScale(1.1));
+label.use(k.rotate(5));
 ```
 
-#### _**Common use cases**_
+kaplay-ui never locks you into a restricted UI model.
+
+---
+
+## 🧠 Design philosophy
+
+kaplay-ui is intentionally simple:
+
+- ✅ No retained UI trees
+- ✅ No layout engine
+- ✅ No reactive framework
+- ✅ Just KAPLAY game objects + helpers
+
+You stay in control of how and when UI updates happen.
 
-- HUD overlays
-- Score counters
-- Time and health displays
-- UI section headings
-- Tooltips and indicators
+---
+
+## 📚 Documentation
+
+- Full API documentation is available via **JSDocs**
+- All helpers are strongly typed and editor-friendly
+- Hover over methods in your editor to explore options
 
 ---
 
 ## 🛣️ Roadmap
 
-_See evolving roadmap at: https://github.com/jbakchr/kaplay-ui/blob/v1/ROADMAP.md_
+Future components may include:
+
+- Toggles
+- Sliders
+- Panels / containers
+
+See the roadmap here:  
+👉 <https://github.com/jbakchr/kaplay-ui/blob/v1/ROADMAP.md>
 
 ---
 

package/dist/uiplugin.js

@@ -1,62 +1,48 @@
-//#region src/components/button/index.ts
+//#region src/helpers/color-utils.ts
 function e(e, t, n) {
-	let { width: r, height: i, radius: a, posX: o, posY: s, outline: c } = {
-		width: 150,
-		height: 60,
-		radius: 10,
-		posX: 0,
-		posY: 0,
-		outline: 3,
-		...t
-	};
-	return e.make([
-		e.rect(r, i, { radius: a }),
-		e.pos(o, s),
-		e.color(200, 200, 200),
-		e.outline(c, e.rgb(92, 91, 91)),
-		e.anchor(n),
-		e.area()
-	]);
+	if (Array.isArray(n)) {
+		t.use(e.color([
+			n[0],
+			n[1],
+			n[2]
+		]));
+		return;
+	}
+	if (typeof n == "string") {
+		t.use(e.color(n));
+		return;
+	}
+	if (typeof n == "object" && "r" in n) {
+		t.use(e.color(e.rgb(n.r, n.g, n.b)));
+		return;
+	}
+	t.use(e.color(n));
 }
-//#endregion
-//#region src/components/label/index.ts
-function t(e, t) {
-	let { width: n, height: r } = {
-		width: 160,
-		height: 96,
-		...t
-	};
-	return e.make([
-		e.rect(n, r),
-		e.pos(0, 0),
-		e.color(0, 0, 0),
-		e.opacity(.7),
-		e.anchor("topleft")
-	]);
+function t(e, t, n, r) {
+	if (typeof r == "string") {
+		t.use(e.outline(n, e.rgb(r)));
+		return;
+	}
+	if (Array.isArray(r)) {
+		t.use(e.outline(n, e.rgb(r[0], r[1], r[2])));
+		return;
+	}
 }
 //#endregion
-//#region src/components/text/index.ts
-function n(e, t, n, r, i, a) {
-	let { txtSize: o } = {
-		txtSize: 22,
-		...n
-	};
-	return e.make([
-		e.text(t, { size: o }),
-		e.color(0, 0, 0),
-		e.pos(r, i),
-		e.anchor(a)
-	]);
+//#region src/helpers/layout-utils.ts
+var n = new Set(["anchor", "rect"]);
+function r(e) {
+	return n.has(e);
 }
 //#endregion
 //#region src/helpers/pos-utils.ts
-function r(e) {
+function i(e) {
 	return {
 		cX: e.width / 2,
 		cY: e.height / 2
 	};
 }
-function i(e, t, n, r, i) {
+function a(e, t, n, r, i) {
 	switch (t.anchor) {
 		case "bot":
 			n.use(e.pos(0 * r, -1 * i));
@@ -89,43 +75,189 @@ function i(e, t, n, r, i) {
 	}
 }
 //#endregion
-//#region src/helpers/layout-utils.ts
-var a = new Set([
-	"anchor",
-	"pos",
-	"area"
-]);
-function o(e) {
-	return a.has(e);
+//#region src/components/label.ts
+function o(t, n) {
+	let { width: r, height: o, radius: s, posX: c, posY: l, opacity: u, lblColor: d } = {
+		width: 160,
+		height: 96,
+		radius: 0,
+		posX: 0,
+		posY: 0,
+		opacity: .7,
+		lblColor: [
+			0,
+			0,
+			0
+		],
+		...n
+	}, f = t.make([
+		t.rect(r, o, { radius: s }),
+		t.pos(c, l),
+		t.opacity(u),
+		t.anchor("topleft"),
+		{
+			setSize(e, n) {
+				f.width = e, f.height = n;
+				let { cX: r, cY: o } = i(f);
+				a(t, f, f.children[0], r, o);
+			},
+			setRadius(e) {
+				f.radius = e;
+			},
+			setPosition(e, t) {
+				f.pos.x = e, f.pos.y = t;
+			},
+			setOpacity(e) {
+				f.opacity = e;
+			},
+			setLabelColor(n) {
+				e(t, f, n);
+			},
+			setLabelText(e) {
+				let t = f.children[0];
+				t.text = e;
+			},
+			setLabelTextColor(n) {
+				let r = f.children[0];
+				e(t, r, n);
+			},
+			setLabelTextSize(e) {
+				let t = f.children[0];
+				t.textSize = e;
+			},
+			setLabelAnchor(e) {
+				f.anchor = e;
+				let { cX: n, cY: r } = i(f);
+				a(t, f, f.children[0], n, r);
+			}
+		}
+	]);
+	return e(t, f, d), f;
 }
 //#endregion
-//#region src/elements/text-button/index.ts
-function s(t, a, s) {
-	let c = e(t, s, "topleft"), { cX: l, cY: u } = r(c), d = n(t, a, s, l, u, "center");
-	return c.add(d), t.add(c), c.onUse((e) => {
-		if (o(e)) {
-			let { cX: e, cY: n } = r(c);
-			i(t, c, d, e, n);
+//#region src/components/button.ts
+function s(n, r, o) {
+	let { width: s, height: c, posX: l, posY: u, radius: d, outline: f, btnColor: p, outlineColor: m } = {
+		width: 150,
+		height: 60,
+		posX: 0,
+		posY: 0,
+		radius: 10,
+		outline: 3,
+		btnColor: [
+			200,
+			200,
+			200
+		],
+		outlineColor: "#5c5b5b",
+		...r
+	}, h = n.make([
+		n.rect(s, c, { radius: d }),
+		n.pos(l, u),
+		n.anchor(o),
+		n.area(),
+		{
+			setSize(e, t) {
+				h.width = e, h.height = t;
+				let { cX: r, cY: o } = i(h);
+				a(n, h, h.children[0], r, o);
+			},
+			setPosition(e, t) {
+				h.pos.x = e, h.pos.y = t;
+			},
+			setRadius(e) {
+				h.radius = e;
+			},
+			setOutline(e) {
+				t(n, h, e, m);
+			},
+			setButtonText(e) {
+				let t = h.children[0];
+				t.text = e;
+			},
+			setButtonTextSize(e) {
+				let t = h.children[0];
+				t.textSize = e;
+			},
+			setButtonColor(t) {
+				e(n, h, t);
+			},
+			setButtonOutlineColor(e) {
+				t(n, h, f, e);
+			},
+			setAnchor(e) {
+				h.anchor = e;
+				let { cX: t, cY: r } = i(h);
+				a(n, h, h.children[0], t, r);
+			},
+			setButtonTextColor(t) {
+				let r = h.children[0];
+				e(n, r, t);
+			}
+		}
+	]);
+	return e(n, h, p), t(n, h, f, m), h;
+}
+//#endregion
+//#region src/components/text.ts
+function c(t, n, r, i, a, o) {
+	let { txtSize: s, txtColor: c } = {
+		txtSize: 22,
+		...r
+	}, l = t.make([
+		t.text(n, { size: s }),
+		t.pos(i, a),
+		t.anchor(o)
+	]);
+	return e(t, l, c), l;
+}
+//#endregion
+//#region src/elements/label.ts
+function l(e, t, n) {
+	let s = {
+		txtColor: [
+			255,
+			255,
+			255
+		],
+		...n
+	}, l = o(e, s), { cX: u, cY: d } = i(l), f = c(e, t, s, u, d, "center");
+	return l.add(f), e.add(l), l.onUse((t) => {
+		if (r(t)) {
+			let { cX: t, cY: n } = i(l);
+			a(e, l, f, t, n);
 		}
-	}), c.onHover(() => {
-		t.setCursor("pointer");
-	}), c.onHoverEnd(() => {
-		t.setCursor("default");
-	}), c;
+	}), l;
 }
 //#endregion
-//#region src/elements/label/index.ts
-function c(e, i, a) {
-	let o = t(e, a), { cX: s, cY: c } = r(o), l = n(e, i, a, s, c, "center");
-	return l.use(e.color(255, 255, 255)), o.add(l), e.add(o), o;
+//#region src/elements/text-button.ts
+function u(e, t, n) {
+	let o = {
+		txtColor: [
+			0,
+			0,
+			0
+		],
+		...n
+	}, l = s(e, o, "topleft"), { cX: u, cY: d } = i(l), f = c(e, t, o, u, d, "center");
+	return l.add(f), e.add(l), l.onUse((t) => {
+		if (r(t)) {
+			let { cX: t, cY: n } = i(l);
+			a(e, l, f, t, n);
+		}
+	}), l.onHover(() => {
+		e.setCursor("pointer");
+	}), l.onHoverEnd(() => {
+		e.setCursor("default");
+	}), l;
 }
 //#endregion
 //#region src/index.ts
-function l(e) {
+function d(e) {
 	return {
-		addTextButton: (t, n = {}) => s(e, t, n),
-		addLabel: (t, n = {}) => c(e, t, n)
+		addTextButton: (t, n = {}) => u(e, t, n),
+		addLabel: (t, n = {}) => l(e, t, n)
 	};
 }
 //#endregion
-export { l as default };
+export { d as default };

package/dist/uiplugin.umd.cjs

@@ -1 +1 @@
-(function(e,t){typeof exports==`object`&&typeof module<`u`?module.exports=t():typeof define==`function`&&define.amd?define([],t):(e=typeof globalThis<`u`?globalThis:e||self,e.uiPlugin=t())})(this,function(){function e(e,t,n){let{width:r,height:i,radius:a,posX:o,posY:s,outline:c}={width:150,height:60,radius:10,posX:0,posY:0,outline:3,...t};return e.make([e.rect(r,i,{radius:a}),e.pos(o,s),e.color(200,200,200),e.outline(c,e.rgb(92,91,91)),e.anchor(n),e.area()])}function t(e,t){let{width:n,height:r}={width:160,height:96,...t};return e.make([e.rect(n,r),e.pos(0,0),e.color(0,0,0),e.opacity(.7),e.anchor(`topleft`)])}function n(e,t,n,r,i,a){let{txtSize:o}={txtSize:22,...n};return e.make([e.text(t,{size:o}),e.color(0,0,0),e.pos(r,i),e.anchor(a)])}function r(e){return{cX:e.width/2,cY:e.height/2}}function i(e,t,n,r,i){switch(t.anchor){case`bot`:n.use(e.pos(0*r,-1*i));break;case`botleft`:n.use(e.pos(1*r,-1*i));break;case`botright`:n.use(e.pos(-1*r,-1*i));break;case`center`:n.use(e.pos(0*r,0*i));break;case`left`:n.use(e.pos(1*r,0*i));break;case`right`:n.use(e.pos(-1*r,0*i));break;case`top`:n.use(e.pos(0*r,1*i));break;case`topleft`:n.use(e.pos(1*r,1*i));break;case`topright`:n.use(e.pos(-1*r,1*i));break;default:break}}var a=new Set([`anchor`,`pos`,`area`]);function o(e){return a.has(e)}function s(t,a,s){let c=e(t,s,`topleft`),{cX:l,cY:u}=r(c),d=n(t,a,s,l,u,`center`);return c.add(d),t.add(c),c.onUse(e=>{if(o(e)){let{cX:e,cY:n}=r(c);i(t,c,d,e,n)}}),c.onHover(()=>{t.setCursor(`pointer`)}),c.onHoverEnd(()=>{t.setCursor(`default`)}),c}function c(e,i,a){let o=t(e,a),{cX:s,cY:c}=r(o),l=n(e,i,a,s,c,`center`);return l.use(e.color(255,255,255)),o.add(l),e.add(o),o}function l(e){return{addTextButton:(t,n={})=>s(e,t,n),addLabel:(t,n={})=>c(e,t,n)}}return l});
+(function(e,t){typeof exports==`object`&&typeof module<`u`?module.exports=t():typeof define==`function`&&define.amd?define([],t):(e=typeof globalThis<`u`?globalThis:e||self,e.uiPlugin=t())})(this,function(){function e(e,t,n){if(Array.isArray(n)){t.use(e.color([n[0],n[1],n[2]]));return}if(typeof n==`string`){t.use(e.color(n));return}if(typeof n==`object`&&`r`in n){t.use(e.color(e.rgb(n.r,n.g,n.b)));return}t.use(e.color(n))}function t(e,t,n,r){if(typeof r==`string`){t.use(e.outline(n,e.rgb(r)));return}if(Array.isArray(r)){t.use(e.outline(n,e.rgb(r[0],r[1],r[2])));return}}var n=new Set([`anchor`,`rect`]);function r(e){return n.has(e)}function i(e){return{cX:e.width/2,cY:e.height/2}}function a(e,t,n,r,i){switch(t.anchor){case`bot`:n.use(e.pos(0*r,-1*i));break;case`botleft`:n.use(e.pos(1*r,-1*i));break;case`botright`:n.use(e.pos(-1*r,-1*i));break;case`center`:n.use(e.pos(0*r,0*i));break;case`left`:n.use(e.pos(1*r,0*i));break;case`right`:n.use(e.pos(-1*r,0*i));break;case`top`:n.use(e.pos(0*r,1*i));break;case`topleft`:n.use(e.pos(1*r,1*i));break;case`topright`:n.use(e.pos(-1*r,1*i));break;default:break}}function o(t,n){let{width:r,height:o,radius:s,posX:c,posY:l,opacity:u,lblColor:d}={width:160,height:96,radius:0,posX:0,posY:0,opacity:.7,lblColor:[0,0,0],...n},f=t.make([t.rect(r,o,{radius:s}),t.pos(c,l),t.opacity(u),t.anchor(`topleft`),{setSize(e,n){f.width=e,f.height=n;let{cX:r,cY:o}=i(f);a(t,f,f.children[0],r,o)},setRadius(e){f.radius=e},setPosition(e,t){f.pos.x=e,f.pos.y=t},setOpacity(e){f.opacity=e},setLabelColor(n){e(t,f,n)},setLabelText(e){let t=f.children[0];t.text=e},setLabelTextColor(n){let r=f.children[0];e(t,r,n)},setLabelTextSize(e){let t=f.children[0];t.textSize=e},setLabelAnchor(e){f.anchor=e;let{cX:n,cY:r}=i(f);a(t,f,f.children[0],n,r)}}]);return e(t,f,d),f}function s(n,r,o){let{width:s,height:c,posX:l,posY:u,radius:d,outline:f,btnColor:p,outlineColor:m}={width:150,height:60,posX:0,posY:0,radius:10,outline:3,btnColor:[200,200,200],outlineColor:`#5c5b5b`,...r},h=n.make([n.rect(s,c,{radius:d}),n.pos(l,u),n.anchor(o),n.area(),{setSize(e,t){h.width=e,h.height=t;let{cX:r,cY:o}=i(h);a(n,h,h.children[0],r,o)},setPosition(e,t){h.pos.x=e,h.pos.y=t},setRadius(e){h.radius=e},setOutline(e){t(n,h,e,m)},setButtonText(e){let t=h.children[0];t.text=e},setButtonTextSize(e){let t=h.children[0];t.textSize=e},setButtonColor(t){e(n,h,t)},setButtonOutlineColor(e){t(n,h,f,e)},setAnchor(e){h.anchor=e;let{cX:t,cY:r}=i(h);a(n,h,h.children[0],t,r)},setButtonTextColor(t){let r=h.children[0];e(n,r,t)}}]);return e(n,h,p),t(n,h,f,m),h}function c(t,n,r,i,a,o){let{txtSize:s,txtColor:c}={txtSize:22,...r},l=t.make([t.text(n,{size:s}),t.pos(i,a),t.anchor(o)]);return e(t,l,c),l}function l(e,t,n){let s={txtColor:[255,255,255],...n},l=o(e,s),{cX:u,cY:d}=i(l),f=c(e,t,s,u,d,`center`);return l.add(f),e.add(l),l.onUse(t=>{if(r(t)){let{cX:t,cY:n}=i(l);a(e,l,f,t,n)}}),l}function u(e,t,n){let o={txtColor:[0,0,0],...n},l=s(e,o,`topleft`),{cX:u,cY:d}=i(l),f=c(e,t,o,u,d,`center`);return l.add(f),e.add(l),l.onUse(t=>{if(r(t)){let{cX:t,cY:n}=i(l);a(e,l,f,t,n)}}),l.onHover(()=>{e.setCursor(`pointer`)}),l.onHoverEnd(()=>{e.setCursor(`default`)}),l}function d(e){return{addTextButton:(t,n={})=>u(e,t,n),addLabel:(t,n={})=>l(e,t,n)}}return d});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaplay-ui",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.14",
   "description": "UI components for KAPLAY",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -2,9 +2,9 @@ import type { KAPLAYCtx } from "kaplay";
 
 // Types
 import {
+  ButtonComponent,
   LabelComponent,
   LabelOptions,
-  TextButtonElement,
   TextButtonOptions,
 } from "./types";
 
@@ -12,31 +12,73 @@ import {
 import { createLabel, createTextButton } from "./elements";
 
 /**
- * # KAPLAY UI Plugin
+ * # KAPLAY-UI Plugin
  *
- * A small UI helper plugin that adds convenience functions for creating
- * common UI components such as buttons and labels within a KAPLAY game.
+ * A lightweight UI helper plugin that extends the KAPLAY context (`k`)
+ * with convenience methods for creating common, reusable UI components
+ * such as text buttons and labels.
  *
- * ## Available UI Creation Helpers
+ * This plugin focuses on *simple, code-driven UI composition* by providing
+ * sensible defaults while still allowing full runtime control over layout,
+ * styling, and text.
  *
- * @returns {object} An object exposing UI creation helpers on `k`:
- * - `addTextButton(txt, opts?) → TextButtonElement`
- * - `addLabel(txt, opts?) → LabelComponent`
+ * ---
  *
- * ## Examples
+ * ## What this plugin does
+ * When included via `kaplay({ plugins: [...] })`, this plugin augments
+ * the existing KAPLAY context with the following helper methods:
+ *
+ * - `k.addTextButton(txt, opts?) → ButtonComponent`
+ *   Creates an interactive button with centered text and exposes methods
+ *   for updating size, position, colors, radius, outline, anchor, and text
+ *   properties at runtime.
+ *
+ * - `k.addLabel(txt, opts?) → LabelComponent`
+ *   Creates a non-interactive text label with a background surface and
+ *   exposes methods for dynamically updating layout, appearance, and text.
+ *
+ * These helpers eliminate the need to manually wire up common UI primitives
+ * while still returning fully controllable game objects.
+ *
+ * ---
+ *
+ * ## Design philosophy
+ * - No layout system or retained UI tree
+ * - No reactivity framework
+ * - No hidden state
+ *
+ * UI elements are regular KAPLAY game objects with small, focused helper
+ * methods attached for convenience.
+ *
+ * ---
+ *
+ * ## Usage
  *
  * @example
  * import kaplay from "kaplay";
- * import kaplayUI from "kaplay-ui"
+ * import kaplayUI from "kaplay-ui";
  *
  * const k = kaplay({
- *    plugins: [kaplayUI]
- * })
+ *   plugins: [kaplayUI],
+ * });
  *
- * const button = k.addTextButton("Start");
- * const label = k.addLabel("Hello!");
+ * const btn = k.addTextButton("Start");
+ * btn.onClick(() => console.log("Game starting…"));
+ *
+ * const label = k.addLabel("Score: 0");
+ * label.setPosition(20, 20);
+ *
+ * ---
+ *
+ * @returns {{
+ *   addTextButton: Function,
+ *   addLabel: Function
+ * }}
+ * Kaplay merges the returned object into the `k` context, making the
+ * UI helpers available as `k.addTextButton()` and `k.addLabel()`.
+ *
+ * The plugin itself does not create or return UI elements directly.
  */
-
 export default function kaplayUI(k: KAPLAYCtx): {
   /**
    * # Text Button
@@ -45,93 +87,217 @@ export default function kaplayUI(k: KAPLAYCtx): {
    * This helper provides sensible defaults for size, layout, and styling<br>
    * so you can quickly add text-based buttons to your KAPLAY game or UI.
    *
+   * ---
+   *
    * ## Parameters
    *
-   * ### Required Paramters
+   * ### Required Parameters
    * - `txt` {string}
+   *   Initial text label displayed at the center of the button.
    *
-   * ### Default Parameter Values for 'opts'
+   * ### Default Parameter Values for `opts`
    * - `opts.width`: `150`
    * - `opts.height`: `60`
-   * - `opts.radius`: `10`
    * - `opts.posX`: `0`
    * - `opts.posY`: `0`
+   * - `opts.radius`: `10`
    * - `opts.outline`: `3`
+   * - `opts.btnColor`: `[200, 200, 200]`
+   * - `opts.outlineColor`: `"#5c5b5b"`
+   * - `opts.txtSize`: `20`
+   * - `opts.txtColor`: `[0, 0, 0]`
+   * ---
    *
    * ## Default Styling
    * The button object is created with:
    * - `k.anchor("topleft")`
-   * - `k.color(200, 200, 200)`
-   * - `k.outline(opts.outline, k.rgb(92, 91, 91))`
    * - `k.area()`
    *
-   * @param {string} [txt]
+   * The button text is created with:
+   * - `k.anchor("center")`
+   *
+   * ---
+   *
+   * ## Button Instance Methods
+   * The returned `ButtonComponent` exposes the following mutator methods,
+   * allowing the button to be updated after creation:
+   *
+   * ### Layout & Geometry
+   * - `setSize(w: number, h: number): void`
+   *   Update the button width and height.
+   *
+   * - `setPosition(x: number, y: number): void`
+   *   Move the button to a new position.
+   *
+   * - `setAnchor(a: Anchor): void`
+   *   Change the anchor used for positioning.
+   *
+   * - `setRadius(r: number): void`
+   *   Update the corner radius.
+   *
+   * - `setOutline(t: number): void`
+   *   Set the outline thickness.
+   *
+   * ### Text
+   * - `setButtonText(txt: string): void`
+   *   Replace the button label.
+   *
+   * - `setButtonTextSize(size: number): void`
+   *   Change the font size of the button text.
+   *
+   * - `setButtonTextColor(color: KaplayColor): void`
+   *   Update the text color.
+   *
+   * ### Colors
+   * - `setButtonColor(color: KaplayColor): void`
+   *   Change the button fill color.
+   *
+   * - `setButtonOutlineColor(color: KaplayRGB): void`
+   *   Change the outline stroke color.
+   *
+   * ---
+   *
+   * @param {string} txt
    *   Required text label to be displayed at the center of the button.
    *
    * @param {TextButtonOptions} [opts={}]
    *   Optional configuration object used to customize the button.
    *
-   * @returns {TextButtonElement}
-   *   A KAPLAY Game Object representing the button with centered text.
+   * @returns {ButtonComponent}
+   *   A clickable button instance with runtime mutation helpers attached.
+   *
+   * ---
    *
    * @example
-   * // Basic usage (uses default width/height)
+   * // Basic usage
    * const playBtn = addTextButton("Play");
    * playBtn.onClick(() => console.log("Play clicked!"));
    *
    * @example
-   * // Custom sizing
-   * const bigBtn = addTextButton("Start", { width: 300, height: 120 });
+   * // Runtime mutation
+   * const btn = addTextButton("Start");
+   * btn.setSize(300, 120);
+   * btn.setButtonColor([255, 100, 100]);
+   * btn.setButtonText("Go!");
    *
    * @example
-   * // Override only one dimension
-   * const tallBtn = addTextButton("Options", { radius: 2 });
+   * // Visual-only updates
+   * const optionsBtn = addTextButton("Options", { radius: 2 });
+   * optionsBtn.setButtonOutlineColor([0, 0, 0]);
+   * optionsBtn.setButtonTextSize(24);
    */
-  addTextButton(txt: string, opts?: TextButtonOptions): TextButtonElement;
+  addTextButton(txt: string, opts?: TextButtonOptions): ButtonComponent;
+
   /**
    * # Label
-   *
    * Creates a simple text container with a background and layout box.
    *
    * Labels are lightweight UI elements used to display non-interactive text
    * such as titles, descriptions, or dynamic info (scores, status, etc.).
    *
+   * ---
+   *
    * ## Parameters
    *
-   * ### Required Paramters
+   * ### Required Parameters
    * - `txt` {string}
+   *   Initial label text content.
    *
-   * ### Default Parameter Values for 'opts'
+   * ### Default Parameter Values for `opts`
    * - `opts.width`: `160`
    * - `opts.height`: `96`
+   * - `opts.posX`: `0`
+   * - `opts.posY`: `0`
+   * - `opts.opacity`: `0.7`
    * - `opts.txtSize`: `22`
    *
-   * ## Default Styling
+   * ---
    *
-   * A labels base (its 'background' surface) includes:
-   * - `k.pos(0, 0)`
+   * ## Default Styling
+   * The label background ("base") includes:
    * - `k.color(0, 0, 0)`
-   * - `k.opacity(0.7)`
    * - `k.anchor("topleft")`
    *
-   * A label centered text includes:
-   * - `k.anchor("center"))
-   * - `k.color(255, 255, 255))
+   * The centered label text includes:
+   * - `k.anchor("center")`
+   * - `k.color(255, 255, 255)`
+   *
+   * ---
+   *
+   * ## Label Instance Methods
+   * The returned `LabelComponent` exposes helper methods that allow
+   * the label to be updated dynamically at runtime.
+   *
+   * ### Layout & Geometry
+   * - `setSize(w: number, h: number): void`
+   *   Update the label width and height.
+   *
+   * - `setPosition(x: number, y: number): void`
+   *   Move the label to a new position.
+   *
+   * - `setRadius(r: number): void`
+   *   Update the background corner radius.
+   *
+   * - `setLabelAnchor(anchor: Anchor): void`
+   *   Change the anchor used for positioning the label.
+   *
+   * ### Appearance
+   * - `setOpacity(o: number): void`
+   *   Set label background opacity (0–1).
+   *
+   * - `setLabelColor(c: KaplayColor): void`
+   *   Change the background color of the label.
+   *
+   * ### Text
+   * - `setLabelText(txt: string): void`
+   *   Replace the label text.
+   *
+   * - `setLabelTextSize(size: number): void`
+   *   Change the font size of the label text.
+   *
+   * - `setLabelTextColor(c: KaplayColor): void`
+   *   Update the label text color.
+   *
+   * ---
+   *
+   * @param {string} txt
+   *   Required text content for the label.
    *
    * @param {LabelOptions} [opts={}]
-   *   Optional configuration object used to customize the button.
+   *   Optional configuration object used to customize the label.
    *
-   * @returns {LabelElement}
-   *   A KAPLAY game object representing a text label.
+   * @returns {LabelComponent}
+   *   A non-interactive label element with runtime mutation helpers attached.
+   *
+   * ---
+   *
+   * @example
+   * // Basic usage
+   * const label = addLabel("Score: 0");
+   * label.setPosition(20, 20);
    *
    * @example
-   * let score = 0
+   * // Dynamic text updates (e.g. score counter)
+   * let score = 0;
    * const scoreLabel = addLabel(`Score: ${score}`);
    *
    * k.wait(2, () => {
    *   score++;
-   *   scoreLabel.children[0].text = `Score: ${score}`;
-   * })
+   *   scoreLabel.setLabelText(`Score: ${score}`);
+   * });
+   *
+   * @example
+   * // Runtime appearance updates
+   * const title = addLabel("Game Over", { txtSize: 36 });
+   * title.setLabelColor([40, 40, 40]);
+   * title.setLabelTextColor([255, 80, 80]);
+   * title.setOpacity(0.9);
+   *
+   * @example
+   * // Layout adjustment after creation
+   * const hudLabel = addLabel("Paused");
+   * hudLabel.setSize(200, 60);
+   * hudLabel.setLabelAnchor("center");
    */
   addLabel(txt: string, opts?: LabelOptions): LabelComponent;
 } {
@@ -139,8 +305,8 @@ export default function kaplayUI(k: KAPLAYCtx): {
     addTextButton: (
       txt: string,
       opts: TextButtonOptions = {},
-    ): TextButtonElement => createTextButton(k, txt, opts),
-    addLabel: (txt, opts: LabelOptions = {}): LabelComponent =>
+    ): ButtonComponent => createTextButton(k, txt, opts),
+    addLabel: (txt: string, opts: LabelOptions = {}): LabelComponent =>
       createLabel(k, txt, opts),
   };
 }