openmascot 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dheeraj Mahra
+
+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

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# openmascot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pixel mascots for any website. Draw a character and its moves in the [OpenMascot](https://github.com/DheerajMahra/openmascot) studio, download its JSON, and put it on a page with a `<Mascot>` React component or one script tag. It reacts to page load, clicks, hovers, timers and your own code.
+
+- No dependencies. The script tag is about 3 KB gzipped.
+- The mascot JSON is treated as data: nothing in it can run code or inject markup.
+- Respects `prefers-reduced-motion`.
+
+## React
+
+```bash
+npm install openmascot
+```
+
+```tsx
+import { Mascot, emit } from "openmascot/react";
+import moss from "./moss.json";
+
+export const App = () => (
+  <>
+    <Mascot doc={moss} position="bottom-right" />
+    <button onClick={() => emit("success")}>Save</button>
+  </>
+);
+```
+
+Needs React 19. Works with server rendering (Next.js and others): the doc is passed through a ref, so it survives hydration.
+
+## Script tag
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/openmascot@0/dist/embed.js" defer></script>
+<open-mascot src="/moss.json" position="bottom-right"></open-mascot>
+
+<script>
+  Mascot.emit("success");
+</script>
+```
+
+Put `moss.json` next to your page. Tags added or removed later start and stop on their own.
+
+## Options
+
+| `<Mascot>` prop    | `<open-mascot>` attribute | Meaning                                                                                 |
+| ------------------ | ------------------------- | --------------------------------------------------------------------------------------- |
+| `doc`              | (property)                | The mascot JSON as an object.                                                           |
+| `src`              | `src`                     | URL of the mascot JSON, when `doc` isn't given.                                         |
+| `position`         | `position`                | `"bottom-right"` or `"bottom-left"` pins it to a corner. Leave it out to render inline. |
+| `scale`            | `scale`                   | Screen pixels per mascot pixel. Default 4.                                              |
+| `name`             | `name`                    | A handle for targeting one mascot.                                                      |
+| `triggers={false}` | `triggers="off"`          | Turns off load, click, hover and timer moves. `emit` and `play` still work.             |
+
+## Playing moves from your code
+
+```ts
+emit("success"); // fires the mascot's "success" event: the studio decides which move plays
+play("wave"); // plays a move by name
+emit("success", { to: "inbox" }); // only the mascot named "inbox"
+```
+
+Both return `true` if a mascot played something. In the script tag they are `Mascot.emit` and `Mascot.play`.
+
+To drive one mascot directly, take a ref (React) or the element (HTML). It has `play()`, `emit()`, `pause()` and `resume()`.
+
+```tsx
+const mascot = useRef<MascotElement>(null);
+
+<Mascot ref={mascot} doc={moss} />;
+mascot.current?.play("wave");
+```
+
+`MascotElement` is exported as a type from `openmascot/react`.
+
+## License
+
+MIT

package/dist/animator.d.ts

@@ -0,0 +1,33 @@
+import type { MascotDoc, MascotFrame } from "./types.js";
+export declare const REST_FRAME: MascotFrame;
+/** `{ pose, hold: 3 }` becomes three identical frames so playback is one index per tick. */
+export declare const expandSequence: (seq: MascotFrame[] | undefined) => MascotFrame[];
+/**
+ * Playback state, and nothing else: which sequence is current and which frame is showing.
+ * No DOM and no timers, so the player drives it and tests can step it directly.
+ * `index === -1` means resting on the default pose.
+ */
+export declare class Animator {
+    current: string | null;
+    index: number;
+    private seqs;
+    private frames;
+    /**
+     * Swap the document. Keeps the current sequence when it still exists.
+     * Returns true when the playing sequence vanished, so the caller can stop its timer.
+     */
+    load(doc: MascotDoc): boolean;
+    /** The frame to draw right now. */
+    get frame(): MascotFrame;
+    /** True while a sequence is playing or held on one of its frames. */
+    get busy(): boolean;
+    frameCount(name: string): number;
+    /** Switch to a sequence from its first frame. False when it is missing or empty. */
+    play(name: string): boolean;
+    /** Leave the current sequence and rest on the default pose. */
+    stop(): void;
+    /** Jump to one frame of a sequence. */
+    seek(name: string, index: number): boolean;
+    /** Move to the next frame. Every sequence plays once, then rests on the default pose. */
+    advance(): void;
+}

package/dist/animator.js

@@ -0,0 +1,88 @@
+export const REST_FRAME = { pose: "default", hold: 1 };
+/** `{ pose, hold: 3 }` becomes three identical frames so playback is one index per tick. */
+export const expandSequence = (seq) => {
+    const frames = [];
+    for (const f of seq ?? []) {
+        const n = Math.max(1, Math.floor(f.hold) || 1);
+        for (let i = 0; i < n; i++)
+            frames.push(f);
+    }
+    return frames;
+};
+/**
+ * Playback state, and nothing else: which sequence is current and which frame is showing.
+ * No DOM and no timers, so the player drives it and tests can step it directly.
+ * `index === -1` means resting on the default pose.
+ */
+export class Animator {
+    constructor() {
+        this.current = null;
+        this.index = -1;
+        this.seqs = {};
+        this.frames = [];
+    }
+    /**
+     * Swap the document. Keeps the current sequence when it still exists.
+     * Returns true when the playing sequence vanished, so the caller can stop its timer.
+     */
+    load(doc) {
+        this.seqs = {};
+        for (const name of Object.keys(doc.sequences)) {
+            this.seqs[name] = expandSequence(doc.sequences[name]);
+        }
+        const keep = this.current ? this.seqs[this.current] : undefined;
+        if (keep && keep.length) {
+            this.frames = keep;
+            this.index = Math.min(this.index, keep.length - 1);
+            return false;
+        }
+        if (this.current !== null) {
+            this.stop();
+            return true;
+        }
+        return false;
+    }
+    /** The frame to draw right now. */
+    get frame() {
+        return this.index >= 0 ? (this.frames[this.index] ?? REST_FRAME) : REST_FRAME;
+    }
+    /** True while a sequence is playing or held on one of its frames. */
+    get busy() {
+        return this.current !== null;
+    }
+    frameCount(name) {
+        return this.seqs[name]?.length ?? 0;
+    }
+    /** Switch to a sequence from its first frame. False when it is missing or empty. */
+    play(name) {
+        const frames = this.seqs[name];
+        if (!frames || frames.length === 0)
+            return false;
+        this.current = name;
+        this.frames = frames;
+        this.index = 0;
+        return true;
+    }
+    /** Leave the current sequence and rest on the default pose. */
+    stop() {
+        this.current = null;
+        this.frames = [];
+        this.index = -1;
+    }
+    /** Jump to one frame of a sequence. */
+    seek(name, index) {
+        const frames = this.seqs[name];
+        if (!frames || frames.length === 0)
+            return false;
+        this.current = name;
+        this.frames = frames;
+        this.index = Math.max(0, Math.min(frames.length - 1, index));
+        return true;
+    }
+    /** Move to the next frame. Every sequence plays once, then rests on the default pose. */
+    advance() {
+        this.index++;
+        if (this.index >= this.frames.length)
+            this.stop();
+    }
+}

package/dist/element.d.ts

@@ -0,0 +1,61 @@
+import type { MascotDoc, MascotPosition } from "./types.js";
+import { MascotPlayer } from "./player.js";
+export declare const MASCOT_TAG = "open-mascot";
+/** Which mascots a page-level call reaches. Without `to`, every mascot on the page. */
+export interface MascotTarget {
+    /** Matches the element's `name` attribute. */
+    to?: string;
+}
+declare const Base: typeof HTMLElement;
+/**
+ * `<open-mascot>`: a mascot that mounts itself when it enters the page and cleans up when it
+ * leaves. Give it a `doc` property (the JSON as an object) or a `src` attribute (a URL to it).
+ *
+ *   <open-mascot src="/moss.json" position="bottom-right" scale="5" name="guide"></open-mascot>
+ */
+export declare class MascotElement extends Base {
+    static observedAttributes: string[];
+    private mounted;
+    private docValue;
+    private fetched;
+    /** Bumped on every unmount so a fetch that lands late is dropped. */
+    private loads;
+    /** Between connect and disconnect. Attribute callbacks during an upgrade come before it. */
+    private live;
+    /** The live player, or null while loading or off the page. */
+    get player(): MascotPlayer | null;
+    /** The mascot JSON as an object. Takes precedence over `src`. */
+    get doc(): MascotDoc | null;
+    set doc(doc: MascotDoc | null);
+    get src(): string | null;
+    set src(src: string | null);
+    /** Screen pixels per mascot cell. Default 4. */
+    get scale(): number;
+    set scale(scale: number);
+    /** Fixed corner placement. Unset renders inline where the element sits. */
+    get position(): MascotPosition | null;
+    set position(position: MascotPosition | null);
+    /** Wire the doc's triggers (load, click, hover, intervals). `triggers="off"` turns them off. */
+    get triggers(): boolean;
+    set triggers(on: boolean);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /** Play a move by name. False if it doesn't exist or the mascot hasn't loaded. */
+    play(name: string): boolean;
+    /** Fire the doc's `custom:<name>` trigger. */
+    emit(name: string): boolean;
+    pause(): void;
+    resume(): void;
+    private remount;
+    private start;
+    private unmount;
+    private reflect;
+}
+/** Register `<open-mascot>`. Safe to call more than once, and a no-op on the server. */
+export declare const defineMascotElement: () => void;
+/** Fire `custom:<name>` on every mascot on the page, or on the ones named `to`. */
+export declare const emit: (name: string, target?: MascotTarget) => boolean;
+/** Play a move on every mascot on the page, or on the ones named `to`. */
+export declare const play: (name: string, target?: MascotTarget) => boolean;
+export {};

package/dist/element.js

@@ -0,0 +1,175 @@
+import { MascotPlayer } from "./player.js";
+export const MASCOT_TAG = "open-mascot";
+/** The styles the player writes on its host for a corner mascot. */
+const CORNER_STYLES = ["position", "zIndex", "bottom", "left", "right"];
+// On the server there is no HTMLElement; the class still has to evaluate so imports don't throw.
+const Base = (typeof HTMLElement === "undefined" ? Object : HTMLElement);
+/**
+ * `<open-mascot>`: a mascot that mounts itself when it enters the page and cleans up when it
+ * leaves. Give it a `doc` property (the JSON as an object) or a `src` attribute (a URL to it).
+ *
+ *   <open-mascot src="/moss.json" position="bottom-right" scale="5" name="guide"></open-mascot>
+ */
+export class MascotElement extends Base {
+    constructor() {
+        super(...arguments);
+        this.mounted = null;
+        this.docValue = null;
+        this.fetched = null;
+        /** Bumped on every unmount so a fetch that lands late is dropped. */
+        this.loads = 0;
+        /** Between connect and disconnect. Attribute callbacks during an upgrade come before it. */
+        this.live = false;
+    }
+    /** The live player, or null while loading or off the page. */
+    get player() {
+        return this.mounted;
+    }
+    /** The mascot JSON as an object. Takes precedence over `src`. */
+    get doc() {
+        return this.docValue;
+    }
+    set doc(doc) {
+        if (doc === this.docValue)
+            return;
+        this.docValue = doc;
+        this.remount();
+    }
+    get src() {
+        return this.getAttribute("src");
+    }
+    set src(src) {
+        this.reflect("src", src);
+    }
+    /** Screen pixels per mascot cell. Default 4. */
+    get scale() {
+        const scale = parseInt(this.getAttribute("scale") ?? "", 10);
+        return Number.isFinite(scale) && scale > 0 ? scale : 4;
+    }
+    set scale(scale) {
+        this.setAttribute("scale", String(scale));
+    }
+    /** Fixed corner placement. Unset renders inline where the element sits. */
+    get position() {
+        const position = this.getAttribute("position");
+        return position === "bottom-left" || position === "bottom-right" ? position : null;
+    }
+    set position(position) {
+        this.reflect("position", position);
+    }
+    /** Wire the doc's triggers (load, click, hover, intervals). `triggers="off"` turns them off. */
+    get triggers() {
+        return this.getAttribute("triggers") !== "off";
+    }
+    set triggers(on) {
+        this.reflect("triggers", on ? null : "off");
+    }
+    connectedCallback() {
+        // A doc assigned before the element was defined is an own property hiding the setter.
+        if (Object.prototype.hasOwnProperty.call(this, "doc")) {
+            const doc = this.doc;
+            delete this.doc;
+            this.docValue = doc;
+        }
+        this.live = true;
+        this.remount();
+    }
+    disconnectedCallback() {
+        this.live = false;
+        this.unmount();
+    }
+    attributeChangedCallback(name, old, value) {
+        if (old === value || !this.live)
+            return;
+        if (name === "scale" && this.mounted)
+            this.mounted.setScale(this.scale);
+        else if (name !== "src" || !this.docValue)
+            this.remount();
+    }
+    /** Play a move by name. False if it doesn't exist or the mascot hasn't loaded. */
+    play(name) {
+        return this.mounted?.play(name) ?? false;
+    }
+    /** Fire the doc's `custom:<name>` trigger. */
+    emit(name) {
+        return this.mounted?.emit(name) ?? false;
+    }
+    pause() {
+        this.mounted?.pause();
+    }
+    resume() {
+        this.mounted?.resume();
+    }
+    remount() {
+        this.unmount();
+        if (!this.isConnected)
+            return;
+        if (this.docValue)
+            return this.start(this.docValue);
+        const src = this.src;
+        if (!src)
+            return;
+        if (this.fetched?.src === src)
+            return this.start(this.fetched.doc);
+        const load = this.loads;
+        fetch(src)
+            .then(r => {
+            if (!r.ok)
+                throw new Error(`HTTP ${r.status}`);
+            return r.json();
+        })
+            .then(doc => {
+            this.fetched = { src, doc };
+            if (load === this.loads)
+                this.start(doc);
+        })
+            .catch((err) => console.warn("mascot: could not load", src, err));
+    }
+    start(doc) {
+        this.mounted = new MascotPlayer(this, doc, {
+            scale: this.scale,
+            position: this.position,
+            triggers: this.triggers
+        });
+    }
+    unmount() {
+        this.loads++;
+        if (!this.mounted)
+            return;
+        this.mounted.destroy();
+        this.mounted = null;
+        for (const prop of CORNER_STYLES)
+            this.style[prop] = "";
+    }
+    reflect(name, value) {
+        if (value === null)
+            this.removeAttribute(name);
+        else
+            this.setAttribute(name, value);
+    }
+}
+MascotElement.observedAttributes = ["src", "scale", "position", "triggers"];
+/** Register `<open-mascot>`. Safe to call more than once, and a no-op on the server. */
+export const defineMascotElement = () => {
+    if (typeof customElements === "undefined" || customElements.get(MASCOT_TAG))
+        return;
+    customElements.define(MASCOT_TAG, MascotElement);
+    // :where() keeps this at zero specificity, so any page style wins.
+    const style = document.createElement("style");
+    style.textContent = `:where(${MASCOT_TAG}){display:inline-block;line-height:0}`;
+    document.head.append(style);
+};
+const mascots = (to) => {
+    if (typeof document === "undefined")
+        return [];
+    const all = Array.from(document.querySelectorAll(MASCOT_TAG));
+    return to === undefined ? all : all.filter(el => el.getAttribute("name") === to);
+};
+/** Fire `custom:<name>` on every mascot on the page, or on the ones named `to`. */
+export const emit = (name, target = {}) => mascots(target.to)
+    .map(el => el.emit?.(name) ?? false)
+    .some(Boolean);
+/** Play a move on every mascot on the page, or on the ones named `to`. */
+export const play = (name, target = {}) => mascots(target.to)
+    .map(el => el.play?.(name) ?? false)
+    .some(Boolean);

package/dist/embed.js

@@ -0,0 +1 @@
+"use strict";(()=>{var w={pose:"default",hold:1},H=i=>{let e=[];for(let t of i!=null?i:[]){let s=Math.max(1,Math.floor(t.hold)||1);for(let r=0;r<s;r++)e.push(t)}return e},d=class{constructor(){this.current=null;this.index=-1;this.seqs={};this.frames=[]}load(e){this.seqs={};for(let s of Object.keys(e.sequences))this.seqs[s]=H(e.sequences[s]);let t=this.current?this.seqs[this.current]:void 0;return t&&t.length?(this.frames=t,this.index=Math.min(this.index,t.length-1),!1):this.current!==null?(this.stop(),!0):!1}get frame(){var e;return this.index>=0&&(e=this.frames[this.index])!=null?e:w}get busy(){return this.current!==null}frameCount(e){var t,s;return(s=(t=this.seqs[e])==null?void 0:t.length)!=null?s:0}play(e){let t=this.seqs[e];return!t||t.length===0?!1:(this.current=e,this.frames=t,this.index=0,!0)}stop(){this.current=null,this.frames=[],this.index=-1}seek(e,t){let s=this.seqs[e];return!s||s.length===0?!1:(this.current=e,this.frames=s,this.index=Math.max(0,Math.min(s.length-1,t)),!0)}advance(){this.index++,this.index>=this.frames.length&&this.stop()}};var R=i=>[parseInt(i.slice(1,3),16),parseInt(i.slice(3,5),16),parseInt(i.slice(5,7),16)],k=(i,e)=>{var c,h;let{w:t,h:s}=i.grid,r=(c=i.poses[e])!=null?c:"",o=document.createElement("canvas");o.width=t,o.height=s;let a=o.getContext("2d");if(!a)return o;let n=a.createImageData(t,s);for(let l=0;l<t*s;l++){let y=r[l];if(!y||y===".")continue;let L=(h=i.palette[parseInt(y,36)])!=null?h:"#000000",[P,q,A]=R(L);n.data[l*4]=P,n.data[l*4+1]=q,n.data[l*4+2]=A,n.data[l*4+3]=255}return a.putImageData(n,0,0),o};var F=i=>{var t,s,r;let e={left:1,right:1,up:0,down:1};for(let o of Object.values((t=i.sequences)!=null?t:{}))for(let a of o){let n=Math.round((s=a.x)!=null?s:0),c=Math.round((r=a.offset)!=null?r:0);e.left=Math.max(e.left,-n),e.right=Math.max(e.right,n),e.up=Math.max(e.up,-c),e.down=Math.max(e.down,c)}return e},m=class{constructor(e){this.scale=e;this.poses=new Map;this.pad={left:1,right:1,up:0,down:1};this.canvas=document.createElement("canvas"),this.canvas.style.imageRendering="pixelated",this.canvas.style.display="block",this.canvas.setAttribute("role","img");let t=this.canvas.getContext("2d");if(!t)throw new Error("mascot: canvas 2d context unavailable");this.ctx=t}setDoc(e){this.doc=e,this.poses.clear();for(let t of Object.keys(e.poses))this.poses.set(t,k(e,t));this.pad=F(e),this.canvas.setAttribute("aria-label",`${e.name} mascot`),this.resize()}setScale(e){this.scale=e,this.resize()}draw(e){var c,h,l;let{w:t,h:s}=this.doc.grid,r=this.scale,o=(c=this.poses.get(e.pose))!=null?c:this.poses.get("default"),a=(((h=e.offset)!=null?h:0)+this.pad.up)*r,n=(((l=e.x)!=null?l:0)+this.pad.left)*r;this.ctx.clearRect(0,0,this.canvas.width,this.canvas.height),o&&this.ctx.drawImage(o,n,a,t*r,s*r)}destroy(){this.canvas.remove()}resize(){let{w:e,h:t}=this.doc.grid,s=this.scale,{left:r,right:o,up:a,down:n}=this.pad;this.canvas.width=(e+r+o)*s,this.canvas.height=(t+a+n)*s,this.canvas.style.width=`${this.canvas.width}px`,this.canvas.style.height=`${this.canvas.height}px`,this.ctx.imageSmoothingEnabled=!1}};var I=i=>i==="load"||i==="click"||i==="hover"?{type:i}:i.startsWith("interval:")?{type:"interval",seconds:parseFloat(i.slice(9))||5}:i.startsWith("custom:")?{type:"custom",name:i.slice(7)}:null,u=class{constructor(e,t){this.host=e;this.sequence=t}},M=class extends u{constructor(){super(...arguments);this.onClick=()=>void this.host.play(this.sequence)}attach(){this.host.el.addEventListener("click",this.onClick),this.host.el.style.cursor="pointer"}detach(){this.host.el.removeEventListener("click",this.onClick),this.host.el.style.cursor=""}},b=class extends u{constructor(){super(...arguments);this.onEnter=()=>{this.host.isBusy()||this.host.play(this.sequence)}}attach(){this.host.el.addEventListener("mouseenter",this.onEnter)}detach(){this.host.el.removeEventListener("mouseenter",this.onEnter)}},x=class extends u{constructor(t,s,r){super(t,s);this.seconds=r;this.id=null}attach(){this.id=setInterval(()=>{this.host.isBusy()||this.host.play(this.sequence)},this.seconds*1e3)}detach(){this.id!==null&&clearInterval(this.id),this.id=null}},p=class{constructor(e,t){this.host=e;this.triggers=[];for(let[s,r]of Object.entries(t)){let o=I(s);(o==null?void 0:o.type)==="click"?this.triggers.push(new M(e,r)):(o==null?void 0:o.type)==="hover"?this.triggers.push(new b(e,r)):(o==null?void 0:o.type)==="interval"&&this.triggers.push(new x(e,r,o.seconds))}}attach(){this.host.el.style.cursor="";for(let e of this.triggers)e.attach()}detach(){for(let e of this.triggers)e.detach()}};var S=()=>typeof window!="undefined"&&typeof window.matchMedia=="function"&&window.matchMedia("(prefers-reduced-motion: reduce)").matches,g=class{constructor(e,t,s={}){this.animator=new d;this.triggers=null;this.timer=null;var r,o,a,n;if(this.el=e,this.reduced=(r=s.reducedMotion)!=null?r:S(),this.renderer=new m((o=s.scale)!=null?o:4),s.position&&(e.style.position="fixed",e.style.zIndex="9999",e.style.bottom="16px",e.style[s.position==="bottom-left"?"left":"right"]="16px"),e.style.lineHeight="0",e.appendChild(this.renderer.canvas),this.setDoc(t),s.triggers!==!1){this.triggers=new p(this,(a=t.triggers)!=null?a:{}),this.triggers.attach();let c=(n=t.triggers)==null?void 0:n.load;c&&this.play(c)}}get canvas(){return this.renderer.canvas}get current(){return this.animator.current}setDoc(e){this.doc=e;let t=this.animator.load(e);this.renderer.setDoc(e),t&&this.stopTimer(),this.draw()}setScale(e){this.renderer.setScale(e),this.draw()}play(e){return this.animator.play(e)?(this.stopTimer(),this.reduced?(this.animator.stop(),this.draw()):this.step(),!0):!1}showFrame(e,t){this.animator.seek(e,t)&&(this.stopTimer(),this.draw())}frameCount(e){return this.animator.frameCount(e)}currentIndex(){return this.animator.index}isPlaying(){return this.timer!==null}pause(){this.stopTimer()}resume(){this.timer===null&&this.animator.current&&this.step()}emit(e){var s;let t=(s=this.doc.triggers)==null?void 0:s[`custom:${e}`];return t?this.play(t):!1}isBusy(){return this.animator.busy}destroy(){var e;this.stopTimer(),(e=this.triggers)==null||e.detach(),this.triggers=null,this.renderer.destroy()}stopTimer(){this.timer!==null&&clearTimeout(this.timer),this.timer=null}step(){this.draw(),this.animator.current!==null&&(this.timer=setTimeout(()=>{this.timer=null,this.animator.advance(),this.step()},this.doc.tick||60))}draw(){this.renderer.draw(this.animator.frame)}};var f="open-mascot",O=["position","zIndex","bottom","left","right"],V=typeof HTMLElement=="undefined"?Object:HTMLElement,v=class extends V{constructor(){super(...arguments);this.mounted=null;this.docValue=null;this.fetched=null;this.loads=0;this.live=!1}get player(){return this.mounted}get doc(){return this.docValue}set doc(t){t!==this.docValue&&(this.docValue=t,this.remount())}get src(){return this.getAttribute("src")}set src(t){this.reflect("src",t)}get scale(){var s;let t=parseInt((s=this.getAttribute("scale"))!=null?s:"",10);return Number.isFinite(t)&&t>0?t:4}set scale(t){this.setAttribute("scale",String(t))}get position(){let t=this.getAttribute("position");return t==="bottom-left"||t==="bottom-right"?t:null}set position(t){this.reflect("position",t)}get triggers(){return this.getAttribute("triggers")!=="off"}set triggers(t){this.reflect("triggers",t?null:"off")}connectedCallback(){if(Object.prototype.hasOwnProperty.call(this,"doc")){let t=this.doc;delete this.doc,this.docValue=t}this.live=!0,this.remount()}disconnectedCallback(){this.live=!1,this.unmount()}attributeChangedCallback(t,s,r){s===r||!this.live||(t==="scale"&&this.mounted?this.mounted.setScale(this.scale):(t!=="src"||!this.docValue)&&this.remount())}play(t){var s,r;return(r=(s=this.mounted)==null?void 0:s.play(t))!=null?r:!1}emit(t){var s,r;return(r=(s=this.mounted)==null?void 0:s.emit(t))!=null?r:!1}pause(){var t;(t=this.mounted)==null||t.pause()}resume(){var t;(t=this.mounted)==null||t.resume()}remount(){var r;if(this.unmount(),!this.isConnected)return;if(this.docValue)return this.start(this.docValue);let t=this.src;if(!t)return;if(((r=this.fetched)==null?void 0:r.src)===t)return this.start(this.fetched.doc);let s=this.loads;fetch(t).then(o=>{if(!o.ok)throw new Error(`HTTP ${o.status}`);return o.json()}).then(o=>{this.fetched={src:t,doc:o},s===this.loads&&this.start(o)}).catch(o=>console.warn("mascot: could not load",t,o))}start(t){this.mounted=new g(this,t,{scale:this.scale,position:this.position,triggers:this.triggers})}unmount(){if(this.loads++,!!this.mounted){this.mounted.destroy(),this.mounted=null;for(let t of O)this.style[t]=""}}reflect(t,s){s===null?this.removeAttribute(t):this.setAttribute(t,s)}};v.observedAttributes=["src","scale","position","triggers"];var T=()=>{if(typeof customElements=="undefined"||customElements.get(f))return;customElements.define(f,v);let i=document.createElement("style");i.textContent=`:where(${f}){display:inline-block;line-height:0}`,document.head.append(i)},E=i=>{if(typeof document=="undefined")return[];let e=Array.from(document.querySelectorAll(f));return i===void 0?e:e.filter(t=>t.getAttribute("name")===i)},D=(i,e={})=>E(e.to).map(t=>{var s,r;return(r=(s=t.emit)==null?void 0:s.call(t,i))!=null?r:!1}).some(Boolean),C=(i,e={})=>E(e.to).map(t=>{var s,r;return(r=(s=t.play)==null?void 0:s.call(t,i))!=null?r:!1}).some(Boolean);window.Mascot={emit:D,play:C};T();})();

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { Animator, expandSequence } from "./animator.js";
+export { MASCOT_TAG, MascotElement, defineMascotElement, emit, play } from "./element.js";
+export type { MascotTarget } from "./element.js";
+export { MascotPlayer, prefersReducedMotion } from "./player.js";
+export { EMPTY_CELL, poseToDataUrl, rasterizePose, sequencePadding } from "./renderer.js";
+export type { MascotPadding } from "./renderer.js";
+export { parseTrigger } from "./triggers.js";
+export type { ParsedTrigger } from "./triggers.js";
+export type { MascotDoc, MascotFrame, MascotOptions, MascotPosition, MascotSequence } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Animator, expandSequence } from "./animator.js";
+export { MASCOT_TAG, MascotElement, defineMascotElement, emit, play } from "./element.js";
+export { MascotPlayer, prefersReducedMotion } from "./player.js";
+export { EMPTY_CELL, poseToDataUrl, rasterizePose, sequencePadding } from "./renderer.js";
+export { parseTrigger } from "./triggers.js";

package/dist/player.d.ts

@@ -0,0 +1,40 @@
+import type { MascotDoc, MascotOptions } from "./types.js";
+export declare const prefersReducedMotion: () => boolean;
+/**
+ * Plays a mascot inside an element. A thin facade: the Animator holds playback state,
+ * the Renderer draws it, the TriggerManager reacts to events. This class owns the timer
+ * and the DOM mount.
+ */
+export declare class MascotPlayer {
+    readonly el: HTMLElement;
+    private doc;
+    private readonly animator;
+    private readonly renderer;
+    private triggers;
+    private timer;
+    private reduced;
+    constructor(el: HTMLElement, doc: MascotDoc, opts?: MascotOptions);
+    get canvas(): HTMLCanvasElement;
+    /** Name of the sequence that is playing, or null at rest. */
+    get current(): string | null;
+    /** Swap the document in place. Keeps the current sequence playing when it still exists. */
+    setDoc(doc: MascotDoc): void;
+    setScale(scale: number): void;
+    /** Start a sequence. It plays once, then the mascot rests on its default pose. */
+    play(name: string): boolean;
+    /** Jump to one frame of a sequence and hold it. For scrubbing in an editor. */
+    showFrame(name: string, index: number): void;
+    frameCount(name: string): number;
+    /** Index into the expanded frames of the current sequence, or -1 at rest. */
+    currentIndex(): number;
+    isPlaying(): boolean;
+    pause(): void;
+    resume(): void;
+    /** Fire a `custom:<name>` trigger. */
+    emit(name: string): boolean;
+    isBusy(): boolean;
+    destroy(): void;
+    private stopTimer;
+    private step;
+    private draw;
+}

package/dist/player.js

@@ -0,0 +1,127 @@
+import { Animator } from "./animator.js";
+import { Renderer } from "./renderer.js";
+import { TriggerManager } from "./triggers.js";
+export const prefersReducedMotion = () => typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+/**
+ * Plays a mascot inside an element. A thin facade: the Animator holds playback state,
+ * the Renderer draws it, the TriggerManager reacts to events. This class owns the timer
+ * and the DOM mount.
+ */
+export class MascotPlayer {
+    constructor(el, doc, opts = {}) {
+        this.animator = new Animator();
+        this.triggers = null;
+        this.timer = null;
+        this.el = el;
+        this.reduced = opts.reducedMotion ?? prefersReducedMotion();
+        this.renderer = new Renderer(opts.scale ?? 4);
+        if (opts.position) {
+            el.style.position = "fixed";
+            el.style.zIndex = "9999";
+            el.style.bottom = "16px";
+            el.style[opts.position === "bottom-left" ? "left" : "right"] = "16px";
+        }
+        el.style.lineHeight = "0";
+        el.appendChild(this.renderer.canvas);
+        this.setDoc(doc);
+        if (opts.triggers !== false) {
+            this.triggers = new TriggerManager(this, doc.triggers ?? {});
+            this.triggers.attach();
+            const load = doc.triggers?.load;
+            if (load)
+                this.play(load);
+        }
+    }
+    get canvas() {
+        return this.renderer.canvas;
+    }
+    /** Name of the sequence that is playing, or null at rest. */
+    get current() {
+        return this.animator.current;
+    }
+    /** Swap the document in place. Keeps the current sequence playing when it still exists. */
+    setDoc(doc) {
+        this.doc = doc;
+        const lost = this.animator.load(doc);
+        this.renderer.setDoc(doc);
+        if (lost)
+            this.stopTimer();
+        this.draw();
+    }
+    setScale(scale) {
+        this.renderer.setScale(scale);
+        this.draw();
+    }
+    /** Start a sequence. It plays once, then the mascot rests on its default pose. */
+    play(name) {
+        if (!this.animator.play(name))
+            return false;
+        this.stopTimer();
+        if (this.reduced) {
+            this.animator.stop();
+            this.draw();
+        }
+        else {
+            this.step();
+        }
+        return true;
+    }
+    /** Jump to one frame of a sequence and hold it. For scrubbing in an editor. */
+    showFrame(name, index) {
+        if (!this.animator.seek(name, index))
+            return;
+        this.stopTimer();
+        this.draw();
+    }
+    frameCount(name) {
+        return this.animator.frameCount(name);
+    }
+    /** Index into the expanded frames of the current sequence, or -1 at rest. */
+    currentIndex() {
+        return this.animator.index;
+    }
+    isPlaying() {
+        return this.timer !== null;
+    }
+    pause() {
+        this.stopTimer();
+    }
+    resume() {
+        if (this.timer === null && this.animator.current)
+            this.step();
+    }
+    /** Fire a `custom:<name>` trigger. */
+    emit(name) {
+        const seq = this.doc.triggers?.[`custom:${name}`];
+        return seq ? this.play(seq) : false;
+    }
+    isBusy() {
+        return this.animator.busy;
+    }
+    destroy() {
+        this.stopTimer();
+        this.triggers?.detach();
+        this.triggers = null;
+        this.renderer.destroy();
+    }
+    stopTimer() {
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    step() {
+        this.draw();
+        if (this.animator.current === null)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.animator.advance();
+            this.step();
+        }, this.doc.tick || 60);
+    }
+    draw() {
+        this.renderer.draw(this.animator.frame);
+    }
+}

package/dist/react.d.ts

@@ -0,0 +1,36 @@
+import type { MascotElement } from "./element.js";
+import type { MascotDoc, MascotPosition } from "./types.js";
+import type { DetailedHTMLProps, HTMLAttributes } from "react";
+export { emit, play } from "./element.js";
+export type { MascotElement, MascotTarget } from "./element.js";
+export type { MascotDoc, MascotPosition } from "./types.js";
+/** What <Mascot> takes. Each prop matches the <open-mascot> property of the same name. */
+export interface MascotProps extends DetailedHTMLProps<HTMLAttributes<MascotElement>, MascotElement> {
+    doc?: MascotDoc;
+    src?: string;
+    scale?: number;
+    position?: MascotPosition;
+    /** A handle for `emit(name, { to })` and `play(name, { to })`. */
+    name?: string;
+    triggers?: boolean;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "open-mascot": MascotElement;
+    }
+}
+declare module "react" {
+    namespace JSX {
+        interface IntrinsicElements {
+            "open-mascot": MascotProps;
+        }
+    }
+}
+/**
+ * `<open-mascot>` for React. React 19 skips non-string props on custom elements when it hydrates
+ * server-rendered HTML, so `doc` and `triggers` go in through a ref callback, which runs on
+ * hydration too. The rest render as attributes.
+ *
+ *   <Mascot doc={moss} name="inbox" scale={3} />
+ */
+export declare const Mascot: ({ doc, triggers, ref, ...props }: MascotProps) => import("react").JSX.Element;

package/dist/react.js

@@ -0,0 +1,34 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { defineMascotElement } from "./element.js";
+export { emit, play } from "./element.js";
+defineMascotElement();
+/**
+ * `<open-mascot>` for React. React 19 skips non-string props on custom elements when it hydrates
+ * server-rendered HTML, so `doc` and `triggers` go in through a ref callback, which runs on
+ * hydration too. The rest render as attributes.
+ *
+ *   <Mascot doc={moss} name="inbox" scale={3} />
+ */
+export const Mascot = ({ doc, triggers, ref, ...props }) => (_jsx("open-mascot", { ...props, ref: (el) => {
+        if (!el)
+            return;
+        // Triggers first: setting them after the doc would mount twice.
+        el.triggers = triggers ?? true;
+        el.doc = doc ?? null;
+        if (typeof ref === "function") {
+            const cleanup = ref(el);
+            return () => {
+                if (cleanup)
+                    cleanup();
+                else
+                    ref(null);
+            };
+        }
+        if (ref)
+            ref.current = el;
+        return () => {
+            if (ref)
+                ref.current = null;
+        };
+    } }));

package/dist/renderer.d.ts

@@ -0,0 +1,33 @@
+import type { MascotDoc, MascotFrame } from "./types.js";
+export declare const EMPTY_CELL = ".";
+/** Turn one pose string into a canvas the size of the grid, one canvas pixel per cell. */
+export declare const rasterizePose: (doc: MascotDoc, pose: string) => HTMLCanvasElement;
+/** A scaled PNG of one pose, for thumbnails and exports. */
+export declare const poseToDataUrl: (doc: MascotDoc, pose: string, scale?: number) => string;
+/** Slack around the grid, in cells, so every frame's offset and slide stays on the canvas. */
+export interface MascotPadding {
+    left: number;
+    right: number;
+    up: number;
+    down: number;
+}
+/**
+ * How far frames push the drawing outside its grid. Always at least one column each side
+ * and one row below, so a mascot without any offsets draws the same as before.
+ */
+export declare const sequencePadding: (doc: MascotDoc) => MascotPadding;
+/** Owns the canvas: sizing, a rasterized-pose cache, and drawing one frame. */
+export declare class Renderer {
+    private scale;
+    readonly canvas: HTMLCanvasElement;
+    private ctx;
+    private doc;
+    private poses;
+    private pad;
+    constructor(scale: number);
+    setDoc(doc: MascotDoc): void;
+    setScale(scale: number): void;
+    draw(f: MascotFrame): void;
+    destroy(): void;
+    private resize;
+}

package/dist/renderer.js

@@ -0,0 +1,114 @@
+export const EMPTY_CELL = ".";
+const hexToRgb = (hex) => [
+    parseInt(hex.slice(1, 3), 16),
+    parseInt(hex.slice(3, 5), 16),
+    parseInt(hex.slice(5, 7), 16)
+];
+/** Turn one pose string into a canvas the size of the grid, one canvas pixel per cell. */
+export const rasterizePose = (doc, pose) => {
+    const { w, h } = doc.grid;
+    const str = doc.poses[pose] ?? "";
+    const canvas = document.createElement("canvas");
+    canvas.width = w;
+    canvas.height = h;
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        return canvas;
+    const img = ctx.createImageData(w, h);
+    for (let i = 0; i < w * h; i++) {
+        const ch = str[i];
+        if (!ch || ch === EMPTY_CELL)
+            continue;
+        const hex = doc.palette[parseInt(ch, 36)] ?? "#000000";
+        const [r, g, b] = hexToRgb(hex);
+        img.data[i * 4] = r;
+        img.data[i * 4 + 1] = g;
+        img.data[i * 4 + 2] = b;
+        img.data[i * 4 + 3] = 255;
+    }
+    ctx.putImageData(img, 0, 0);
+    return canvas;
+};
+/** A scaled PNG of one pose, for thumbnails and exports. */
+export const poseToDataUrl = (doc, pose, scale = 8) => {
+    const src = rasterizePose(doc, pose);
+    const out = document.createElement("canvas");
+    out.width = src.width * scale;
+    out.height = src.height * scale;
+    const ctx = out.getContext("2d");
+    if (!ctx)
+        return "";
+    ctx.imageSmoothingEnabled = false;
+    ctx.drawImage(src, 0, 0, out.width, out.height);
+    return out.toDataURL("image/png");
+};
+/**
+ * How far frames push the drawing outside its grid. Always at least one column each side
+ * and one row below, so a mascot without any offsets draws the same as before.
+ */
+export const sequencePadding = (doc) => {
+    const pad = { left: 1, right: 1, up: 0, down: 1 };
+    for (const seq of Object.values(doc.sequences ?? {})) {
+        for (const f of seq) {
+            const x = Math.round(f.x ?? 0);
+            const y = Math.round(f.offset ?? 0);
+            pad.left = Math.max(pad.left, -x);
+            pad.right = Math.max(pad.right, x);
+            pad.up = Math.max(pad.up, -y);
+            pad.down = Math.max(pad.down, y);
+        }
+    }
+    return pad;
+};
+/** Owns the canvas: sizing, a rasterized-pose cache, and drawing one frame. */
+export class Renderer {
+    constructor(scale) {
+        this.scale = scale;
+        this.poses = new Map();
+        this.pad = { left: 1, right: 1, up: 0, down: 1 };
+        this.canvas = document.createElement("canvas");
+        this.canvas.style.imageRendering = "pixelated";
+        this.canvas.style.display = "block";
+        this.canvas.setAttribute("role", "img");
+        const ctx = this.canvas.getContext("2d");
+        if (!ctx)
+            throw new Error("mascot: canvas 2d context unavailable");
+        this.ctx = ctx;
+    }
+    setDoc(doc) {
+        this.doc = doc;
+        this.poses.clear();
+        for (const name of Object.keys(doc.poses))
+            this.poses.set(name, rasterizePose(doc, name));
+        this.pad = sequencePadding(doc);
+        this.canvas.setAttribute("aria-label", `${doc.name} mascot`);
+        this.resize();
+    }
+    setScale(scale) {
+        this.scale = scale;
+        this.resize();
+    }
+    draw(f) {
+        const { w, h } = this.doc.grid;
+        const s = this.scale;
+        const pose = this.poses.get(f.pose) ?? this.poses.get("default");
+        const offset = ((f.offset ?? 0) + this.pad.up) * s;
+        const x = ((f.x ?? 0) + this.pad.left) * s;
+        this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+        if (pose)
+            this.ctx.drawImage(pose, x, offset, w * s, h * s);
+    }
+    destroy() {
+        this.canvas.remove();
+    }
+    resize() {
+        const { w, h } = this.doc.grid;
+        const s = this.scale;
+        const { left, right, up, down } = this.pad;
+        this.canvas.width = (w + left + right) * s; // slack each side for slides
+        this.canvas.height = (h + up + down) * s; // slack above for hops, below for crouches
+        this.canvas.style.width = `${this.canvas.width}px`;
+        this.canvas.style.height = `${this.canvas.height}px`;
+        this.ctx.imageSmoothingEnabled = false;
+    }
+}

package/dist/triggers.d.ts

@@ -0,0 +1,33 @@
+export type ParsedTrigger = {
+    type: "load" | "click" | "hover";
+} | {
+    type: "interval";
+    seconds: number;
+} | {
+    type: "custom";
+    name: string;
+};
+/** The one place trigger keys ("click", "interval:30", "custom:win") are decoded. */
+export declare const parseTrigger: (key: string) => ParsedTrigger | null;
+/** What a trigger needs from the player. */
+export interface TriggerHost {
+    el: HTMLElement;
+    play(name: string): boolean;
+    isBusy(): boolean;
+}
+/** An event source that starts one sequence. Owns its listeners and cleans them up. */
+export declare abstract class Trigger {
+    protected readonly host: TriggerHost;
+    protected readonly sequence: string;
+    constructor(host: TriggerHost, sequence: string);
+    abstract attach(): void;
+    abstract detach(): void;
+}
+/** Builds triggers from a doc's trigger map. `load` and `custom:*` are handled by the player. */
+export declare class TriggerManager {
+    private readonly host;
+    private triggers;
+    constructor(host: TriggerHost, map: Record<string, string>);
+    attach(): void;
+    detach(): void;
+}

package/dist/triggers.js

@@ -0,0 +1,91 @@
+/** The one place trigger keys ("click", "interval:30", "custom:win") are decoded. */
+export const parseTrigger = (key) => {
+    if (key === "load" || key === "click" || key === "hover")
+        return { type: key };
+    if (key.startsWith("interval:"))
+        return { type: "interval", seconds: parseFloat(key.slice(9)) || 5 };
+    if (key.startsWith("custom:"))
+        return { type: "custom", name: key.slice(7) };
+    return null;
+};
+/** An event source that starts one sequence. Owns its listeners and cleans them up. */
+export class Trigger {
+    constructor(host, sequence) {
+        this.host = host;
+        this.sequence = sequence;
+    }
+}
+class ClickTrigger extends Trigger {
+    constructor() {
+        super(...arguments);
+        this.onClick = () => void this.host.play(this.sequence);
+    }
+    attach() {
+        this.host.el.addEventListener("click", this.onClick);
+        this.host.el.style.cursor = "pointer";
+    }
+    detach() {
+        this.host.el.removeEventListener("click", this.onClick);
+        this.host.el.style.cursor = "";
+    }
+}
+/** Hover does not interrupt a move that is already playing. */
+class HoverTrigger extends Trigger {
+    constructor() {
+        super(...arguments);
+        this.onEnter = () => {
+            if (!this.host.isBusy())
+                this.host.play(this.sequence);
+        };
+    }
+    attach() {
+        this.host.el.addEventListener("mouseenter", this.onEnter);
+    }
+    detach() {
+        this.host.el.removeEventListener("mouseenter", this.onEnter);
+    }
+}
+class IntervalTrigger extends Trigger {
+    constructor(host, sequence, seconds) {
+        super(host, sequence);
+        this.seconds = seconds;
+        this.id = null;
+    }
+    attach() {
+        this.id = setInterval(() => {
+            if (!this.host.isBusy())
+                this.host.play(this.sequence);
+        }, this.seconds * 1000);
+    }
+    detach() {
+        if (this.id !== null)
+            clearInterval(this.id);
+        this.id = null;
+    }
+}
+/** Builds triggers from a doc's trigger map. `load` and `custom:*` are handled by the player. */
+export class TriggerManager {
+    constructor(host, map) {
+        this.host = host;
+        this.triggers = [];
+        for (const [key, sequence] of Object.entries(map)) {
+            const parsed = parseTrigger(key);
+            if (parsed?.type === "click")
+                this.triggers.push(new ClickTrigger(host, sequence));
+            else if (parsed?.type === "hover")
+                this.triggers.push(new HoverTrigger(host, sequence));
+            else if (parsed?.type === "interval") {
+                this.triggers.push(new IntervalTrigger(host, sequence, parsed.seconds));
+            }
+        }
+    }
+    attach() {
+        this.host.el.style.cursor = "";
+        for (const t of this.triggers)
+            t.attach();
+    }
+    detach() {
+        for (const t of this.triggers)
+            t.detach();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/** One step of a sequence. `hold` is how many ticks the pose stays on screen. */
+export interface MascotFrame {
+    pose: string;
+    hold: number;
+    /** Rows to push the drawing down. Reads as a crouch. */
+    offset?: number;
+    /** Columns to push the drawing right (negative = left). Reads as a slide. */
+    x?: number;
+}
+export type MascotSequence = MascotFrame[];
+/**
+ * The whole mascot. Poses are strings with one character per cell, row by row:
+ * "." is transparent, any other character is a base-36 palette index.
+ */
+export interface MascotDoc {
+    id: string;
+    name: string;
+    version: number;
+    grid: {
+        w: number;
+        h: number;
+    };
+    /** Milliseconds per animation tick. */
+    tick: number;
+    palette: string[];
+    poses: Record<string, string>;
+    sequences: Record<string, MascotSequence>;
+    /**
+     * Event → sequence name. Keys: "load", "click", "hover", "interval:<seconds>",
+     * "custom:<name>". Every sequence plays once; between them the mascot rests on its default pose.
+     */
+    triggers: Record<string, string>;
+}
+export type MascotPosition = "bottom-right" | "bottom-left";
+export interface MascotOptions {
+    /** Screen pixels per mascot cell. Default 4. */
+    scale?: number;
+    /** Fixed corner placement. Omit to render inline where the element sits. */
+    position?: MascotPosition | null;
+    /** Force reduced motion on or off. Defaults to the OS preference. */
+    reducedMotion?: boolean;
+    /** Wire the doc's triggers (click, hover, intervals, load). Default true. */
+    triggers?: boolean;
+}

package/dist/types.js

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

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "openmascot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Pixel mascots for any website: a <Mascot> React component and a one-line script tag.",
+  "keywords": [
+    "animation",
+    "canvas",
+    "custom-element",
+    "mascot",
+    "pixel-art",
+    "react",
+    "sprite",
+    "web-component"
+  ],
+  "homepage": "https://github.com/DheerajMahra/openmascot#readme",
+  "bugs": "https://github.com/DheerajMahra/openmascot/issues",
+  "license": "MIT",
+  "author": "Dheeraj Mahra",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DheerajMahra/openmascot.git",
+    "directory": "packages/embed"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "unpkg": "dist/embed.js",
+  "jsdelivr": "dist/embed.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "esbuild": "^0.25.0",
+    "jsdom": "^30.1.3",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "^5",
+    "vitest": "^5.0.5"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && pnpm build:lib && pnpm build:script",
+    "build:lib": "tsc -p tsconfig.build.json && node scripts/add-js-extensions.mjs dist",
+    "build:script": "esbuild src/embed.ts --bundle --format=iife --target=es2018 --minify --outfile=dist/embed.js",
+    "demo": "pnpm build && echo 'Demo: http://localhost:4311/packages/embed/demo/vanilla/' && python3 -m http.server 4311 --directory ../..",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "types": "./dist/index.d.ts"
 }