React widget · CRM / admin chrome

A walker that stays on your rails.

Hosts mark tracks and keep-out zones. The figure walks, hops between bars, talks in short bursts, and turns around instead of covering buttons. Who sees it is entirely your app’s decision — this package has no RBAC.

npm install portal-mascot

Read the contract Open npm

Live figure needs a local build. From the repo root run npm run docs:preview — GitHub Pages copies dist automatically on deploy.

Rails

Mark empty walking tracks, not the whole chrome. This page has three: two in the header gaps and one in the status bar.

Avoid

Put keep-out marks on controls that sit on a rail. These docs keep labels off the rails entirely, so the figure never shares a box with the nav.

Room

Right-click the figure (or Shift/Alt-click) to open the habitat. Escape or the scrim closes it.

Install

Peer dependency: React 18+. Import the component and the CSS. Published files are dist only.

npm install portal-mascot

import { PortalMascot } from "portal-mascot";
import "portal-mascot/styles.css";

{canShow ? <PortalMascot userId={id} displayName={name} /> : null}

Host contract

Mark empty tracks the figure may occupy. Extra rails besides bar are away lanes; it portals between them. This page uses three.

The mascot mounts only after a home rail exists in the DOM. If you render the widget before the chrome, it waits, then attaches.

<div data-portal-mascot-rail="bar"></div>
<div data-portal-mascot-rail="header"></div>
<div data-portal-mascot-rail="header-end"></div>
<button data-portal-mascot-avoid>Notifications</button>
<div data-portal-mascot-ticker>…</div>

Attribute	Role
`data-portal-mascot-rail="bar"`	Home rail. Falls back to the first marked rail.
`data-portal-mascot-rail="…"`	Away rails. Any extra marks besides bar/status; the figure hops among them.
`data-portal-mascot-avoid`	Do not overlap; reverse direction. Use when a control sits on a rail.
`data-portal-mascot-ticker`	Crowd / pause. Legacy `data-status-bar-ticker` is also read.

Constants are exported if you prefer not to hard-code strings: RAIL_ATTR, AVOID_ATTR, TICKER_ATTR.

API

Prop	Type	Default	Description
`enabled`	`boolean`	`true`	Hard off switch. Not a permission system.
`userId`	`string \| number \| null`	—	Per-user persisted walker state.
`displayName`	`string \| null`	—	Used in some spoken lines.
`model`	`"default"`	`"default"`	Sprite set. More models later.

Speak

Dispatch portal-mascot-say (or legacy expert-runner-say) with a short text. Max 48 characters.

window.dispatchEvent(
  new CustomEvent("portal-mascot-say", { detail: { text: "sprint bitti" } })
);

What it does

One sprite model for now. Acts switch on their own as it walks the chrome.

run / walk sit desk coffee (15:00 Istanbul) fishing scooter portal hop

Click knocks it down. A fast click streak makes it flee for a while.
Hover gets a look; staying on it makes it impatient.
Toasts (data-sonner-toast) and tickers count as a crowd — it pauses.
prefers-reduced-motion: reduce parks it sitting on the home rail.

FAQ

Does the package decide who can see the mascot?

No. Mount it only when your host allows it. enabled is just an off switch.

The GitHub repo is private. Can I still use this?

Yes. The npm package is public (publishConfig.access: public). Install from the registry; you do not need repo access.

Why is nothing walking?

There is no home rail, motion is reduced, or enabled is false. This site needs docs/pkg from npm run docs:preview or a Pages deploy.

License

MIT.