brandbot 0.1.0

package/LICENSE

@@ -0,0 +1,42 @@
+MIT License (applies to all code in this package)
+
+Copyright (c) 2026 Aidan Zarski
+
+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.
+
+--------------------------------------------------------------------------
+
+3D Model provenance (src/nexbot-model.js)
+
+The bundled robot model is "NEXBOT - robot character concept", a Spline
+Community file created by the Spline team, exported to glTF.
+
+  Source: https://community.spline.design/file/87343305-102d-4670-bb8e-38252064de27
+  License: CC0 1.0 Universal (public domain dedication)
+           https://creativecommons.org/publicdomain/zero/1.0/
+
+Spline's Community Platform documentation
+(https://docs.spline.design/doc/community-platform/docSaqY7mlFz) states:
+"All the community files are licensed under CC0 1.0 Universal Deed."
+(Verified 2026-06-12. Archived evidence:
+https://web.archive.org/web/20260612220813/https://docs.spline.design/basics/community-platform
+https://web.archive.org/web/20260612220949/https://community.spline.design/file/87343305-102d-4670-bb8e-38252064de27 )
+
+CC0 places the work in the public domain: it may be used, modified, and
+redistributed for any purpose, including commercially, without attribution.

package/README.md

@@ -0,0 +1,137 @@
+# BrandBot 🤖
+
+**A 3D robot mascot you brand with your own logo and colors.** A drop-in React component that gestures, blinks, and follows the visitor's cursor. It renders with [Three.js](https://threejs.org), is written in TypeScript with full type declarations, and bundles the model — so there's nothing to configure or host. Works in any React app (see the Next.js note below).
+
+**[▶ Live demo](https://aidan945.github.io/brandbot/demo/)** · **[Configure & copy code](https://aidan945.github.io/brandbot/demo/configure.html)**
+
+![BrandBot](./preview.png)
+
+## Install
+
+```bash
+npm install brandbot three react
+```
+
+## Use
+
+```jsx
+import { BrandBot } from 'brandbot';
+
+export function Hero() {
+  return (
+    <div style={{ height: 600 }}>
+      <BrandBot primary="#13294b" eyes="#7fd4ff" logoText="ACME" />
+    </div>
+  );
+}
+```
+
+That's it. The component fills its parent, renders on a transparent background, and starts moving. **The default needs no extra CSS** — drop it in a sized box and it looks right.
+
+### Full-bleed hero (optional)
+
+To have the robot rise from the bottom of a full-height hero with its legs fading into the page (like the [demo](https://aidan945.github.io/brandbot/demo/)), wrap it:
+
+```jsx
+<div style={{ height: '100vh', overflow: 'hidden',
+              WebkitMaskImage: 'linear-gradient(180deg,#000 88%,transparent 100%)' }}>
+  <div style={{ position: 'absolute', inset: 0,
+                transform: 'scale(1.1) translateY(8%)', transformOrigin: 'center top' }}>
+    <BrandBot />
+  </div>
+</div>
+```
+
+**By default it stays put** — locked in its box, facing forward, following the cursor. It does *not* let visitors drag-rotate it (rarely what you want in a hero or card). Add `orbit` to enable drag-to-rotate for demos.
+
+## Brand it
+
+Every color and the chest logo is a prop. Drop in your logo as text, an uploaded image (inlined as base64), or a URL:
+
+```jsx
+<BrandBot
+  primary="#0e1a2b"
+  accent="#1d3350"
+  eyes="#7fd4ff"
+  logoImage="/logo.png"   // or logoText="ACME"
+/>
+```
+
+The **[configurator](https://aidan945.github.io/brandbot/demo/configure.html)** lets you tweak everything visually and copies the exact JSX for your setup.
+
+## Props
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `primary` | color | near-black | body shell + carbon parts |
+| `accent` | color | dark metal | joints, mechanical internals |
+| `visor` | color | chrome | face plate |
+| `hands` | color | chrome | hands |
+| `eyes` | color | white-blue | LED dot-matrix eyes |
+| `logoText` | string | — | text logo on the chest (1–3 words) |
+| `logoColor` | color | white | |
+| `logoImage` | url | — | image logo (transparent PNG/SVG best); overrides text |
+| `legs` | boolean | `true` | `false` shows the upper body only |
+| `orbit` | boolean | `false` | `true` lets visitors drag to rotate (for demos) |
+| `intro` | boolean | `true` | one-time zoom-in when the model loads |
+| `trackPointer` | `'window' \| 'element' \| false` | `'window'` | what the head watches |
+| `shadow` | boolean | `true` | soft ground shadow |
+| `modelUrl` | url | bundled | load a different glTF instead of the bundled model |
+| `className`, `style` | | | passed to the wrapper div |
+
+All color/logo/legs props are live — update them in state and the robot changes instantly. (`orbit` and `intro` are set once at mount.)
+
+Imperative handle via ref:
+
+```jsx
+const bot = useRef(null);
+<BrandBot ref={bot} />
+<button onClick={() => bot.current.spin()}>Spin</button>     {/* one full turn   */}
+<button onClick={() => bot.current.replay()}>Replay</button> {/* the zoom-in intro */}
+```
+
+## Next.js
+
+WebGL can't server-render, so load it client-side:
+
+```jsx
+import dynamic from 'next/dynamic';
+const BrandBot = dynamic(() => import('brandbot').then(m => m.BrandBot), { ssr: false });
+```
+
+## Without React
+
+The engine is framework-agnostic:
+
+```js
+import { createBrandbot } from 'brandbot/core';
+import model from 'brandbot/model';
+
+const robot = createBrandbot(document.querySelector('#hero'), { gltf: model });
+robot.set({ primary: '#13294b', logoText: 'ACME' });
+```
+
+## Demo
+
+The `demo/` folder is a no-build static site (works on GitHub Pages):
+
+- **`demo/index.html`** — showcase: the robot rising from a light-grid hero with the zoom-in intro and cursor tracking.
+- **`demo/configure.html`** — live configurator with tabbed code, "copy code", and "copy prompt for agent".
+
+Run `python3 -m http.server` in the package folder and open `demo/index.html`.
+
+## Development
+
+```bash
+npm install      # toolchain (typescript, @types/three, @types/react)
+npm run build    # compile src/*.ts → dist/ (+ .d.ts) and copy the model
+npm run typecheck
+```
+
+Source lives in `src/` (TypeScript). The committed `dist/` is what the demo and
+npm package consume; rebuild it after changing `src/`.
+
+## License
+
+- **Code:** MIT.
+- **Model:** the bundled robot is the [NEXBOT character](https://community.spline.design/file/87343305-102d-4670-bb8e-38252064de27), a Spline Community file under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) (public domain). Per [Spline's docs](https://docs.spline.design/doc/community-platform/docSaqY7mlFz): "All the community files are licensed under CC0 1.0 Universal Deed." Free to use, modify, and redistribute — including commercially — with no attribution required. Credited anyway, because it's a great model.

package/dist/BrandBot.d.ts

@@ -0,0 +1,40 @@
+import type { CSSProperties } from 'react';
+import type { BrandBotHandle, Color, TrackPointer } from './types.js';
+export interface BrandBotProps {
+    primary?: Color;
+    accent?: Color;
+    visor?: Color;
+    hands?: Color;
+    eyes?: Color;
+    logoText?: string;
+    logoColor?: Color;
+    /** Image logo: URL, data URI, or object URL. Overrides `logoText`. */
+    logoImage?: string | null;
+    /** `false` shows the upper body only. */
+    legs?: boolean;
+    /** Let visitors drag to rotate (for demos). */
+    orbit?: boolean;
+    /** One-time zoom-in when the model loads. */
+    intro?: boolean;
+    /** What the head watches. */
+    trackPointer?: TrackPointer;
+    /** Soft ground shadow. */
+    shadow?: boolean;
+    /** Load a different glTF instead of the bundled model. */
+    modelUrl?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * <BrandBot primary="#13294b" eyes="#7fd4ff" logoText="ACME"
+ *           style={{ height: 600 }} />
+ *
+ * A 3D robot mascot you brand with your own logo and colors. It sits locked in
+ * its box, faces forward, and follows the cursor. It does NOT let visitors
+ * drag-rotate unless you pass `orbit` (handy for demos).
+ *
+ * All color/logo props are live — change them and the robot updates.
+ * Use a ref for the imperative bits: ref.current.spin() / ref.current.replay()
+ */
+export declare const BrandBot: import("react").ForwardRefExoticComponent<BrandBotProps & import("react").RefAttributes<BrandBotHandle>>;
+export default BrandBot;

package/dist/BrandBot.js

@@ -0,0 +1,53 @@
+import { createElement, forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import { createBrandbot } from './robot-core.js';
+import model from './nexbot-model.js';
+/**
+ * <BrandBot primary="#13294b" eyes="#7fd4ff" logoText="ACME"
+ *           style={{ height: 600 }} />
+ *
+ * A 3D robot mascot you brand with your own logo and colors. It sits locked in
+ * its box, faces forward, and follows the cursor. It does NOT let visitors
+ * drag-rotate unless you pass `orbit` (handy for demos).
+ *
+ * All color/logo props are live — change them and the robot updates.
+ * Use a ref for the imperative bits: ref.current.spin() / ref.current.replay()
+ */
+export const BrandBot = forwardRef(function BrandBot(props, ref) {
+    const { primary, accent, visor, hands, eyes, logoText, logoColor, logoImage, legs = true, trackPointer = 'window', shadow = true, modelUrl, orbit = false, intro = true, className, style, } = props;
+    const el = useRef(null);
+    const bot = useRef(null);
+    useEffect(() => {
+        if (!el.current)
+            return;
+        bot.current = createBrandbot(el.current, {
+            gltf: modelUrl ? null : model,
+            modelUrl,
+            trackPointer,
+            shadow,
+            legs,
+            orbit,
+            intro,
+            ...(primary && { primary }), ...(accent && { accent }),
+            ...(visor && { visor }), ...(hands && { hands }), ...(eyes && { eyes }),
+            ...(logoText !== undefined && { logoText }),
+            ...(logoColor && { logoColor }), ...(logoImage && { logoImage }),
+        });
+        return () => bot.current?.dispose();
+        // structural options rebuild the scene; colors/logo flow through below
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [modelUrl, trackPointer, shadow, orbit, intro]);
+    useEffect(() => {
+        bot.current?.set({ primary, accent, visor, hands, eyes, logoText, logoColor, logoImage, legs });
+    }, [primary, accent, visor, hands, eyes, logoText, logoColor, logoImage, legs]);
+    useImperativeHandle(ref, () => ({
+        spin: () => bot.current?.spin(),
+        replay: () => bot.current?.replay(),
+        set: (o) => bot.current?.set(o),
+    }), []);
+    return createElement('div', {
+        ref: el,
+        className,
+        style: { width: '100%', height: '100%', ...style },
+    });
+});
+export default BrandBot;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { BrandBot, default } from './BrandBot.js';
+export { createBrandbot } from './robot-core.js';
+export type { BrandbotOptions, BrandbotUpdate, BrandbotInstance, BrandBotHandle, TrackPointer, Color, } from './types.js';
+export type { BrandBotProps } from './BrandBot.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { BrandBot, default } from './BrandBot.js';
+export { createBrandbot } from './robot-core.js';

package/dist/nexbot-model.d.ts

@@ -0,0 +1,3 @@
+// The bundled NEXBOT model (Spline Community file, CC0) as parsed glTF JSON.
+declare const model: unknown;
+export default model;