@klex/mascot 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -97,7 +97,7 @@ Emotes, including jumps and shaking, scale down with the avatar. The ground is t
97
97
 
98
98
  `idle` defaults to `true`. Resting characters breathe gently, sway their heads, blink and occasionally glance around without changing their expression or position. Every instance has its own breathing pace and independently randomized blink and glance pauses. Each glance also varies in direction and duration. The idle pose fades out for travel and emotes, then returns automatically. Flying characters keep their hover. Use `idle={false}` for static avatars or long lists that do not need continuous animation.
99
99
 
100
- `activity` selects a persistent animation and defaults to `'idle'`. `'sleeping'` closes the eyes, lowers and tilts the head, and breathes slowly. `'calling'` holds a bundled Twemoji 📞 SVG against the head, mirrored toward the face and held by a small hand in the body color. A fixed graphic avoids platform-dependent emoji font shapes and baselines. The earpiece follows the deformed silhouette slightly above the eyes, including custom shapes. Each avatar alternates attentive listening, irregular conversational emphasis, and a friendly double nod, with natural blinks and pauses. These are ambient gestures, not speech detection; reduced motion keeps a static listening pose. No laptop is shown. `'working'` places a laptop in front of the character, with its back facing the viewer. Each avatar independently alternates between reading across successive lines, typing in irregular bursts, and looking up to think with a question mark overhead. Phase order, durations, and pauses are randomized anew throughout the animation. `'recalling'` shows a thought bubble with pulsing dots above the head. The character alternates quiet pondering toward the bubble, quick searching glances, and a short happy nod; these are ambient gestures and never claim a memory was found. `'learning'` holds an open book and writes into it with a pencil. Ink fills the right-hand page line by line in uneven bursts, the pen lifts while returning to the start of a line, and the character pauses to reread or think. A full page turns over and writing starts on a fresh page. Travel and emotes take precedence, then the latest activity resumes. `idle={false}` disables only the default idle animation; an explicit sleeping, working, calling, recalling or learning activity still runs.
100
+ `activity` selects a persistent animation and defaults to `'idle'`. `'sleeping'` closes the eyes, lowers and tilts the head, and breathes slowly. `'calling'` holds a bundled Twemoji 📞 SVG against the head, mirrored toward the face and held by a small hand in the body color. A fixed graphic avoids platform-dependent emoji font shapes and baselines. The earpiece follows the deformed silhouette slightly above the eyes, including custom shapes. Each avatar alternates attentive listening, irregular conversational emphasis, and a friendly double nod, with natural blinks and pauses. These are ambient gestures, not speech detection; reduced motion keeps a static listening pose. No laptop is shown. `'working'` places a laptop in front of the character, with its back facing the viewer. Each avatar independently alternates between reading across successive lines, typing in irregular bursts, and looking up to think with a question mark overhead. Phase order, durations, and pauses are randomized anew throughout the animation. `'recalling'` shows a thought bubble with pulsing dots above the head. The character alternates quiet pondering toward the bubble, quick searching glances, and a short happy nod; these are ambient gestures and never claim a memory was found. `'learning'` holds an open book and writes into it with a pencil. Ink fills the right-hand page line by line in uneven bursts, the pen lifts while returning to the start of a line, and the character pauses to reread or think. A full page turns over and writing starts on a fresh page. Travel and emotes take precedence, then the latest activity resumes. A changed activity blends in, so an awake avatar closes its eyes as it falls asleep; a freshly mounted one starts in its activity's pose, and held props still spring in. Pass `activityPending` while `activity` is only a placeholder for a status that is still loading: the first real activity shows at once as well. Once one has shown, every change blends, including a return to a placeholder. `idle={false}` disables only the default idle animation; an explicit sleeping, working, calling, recalling or learning activity still runs.
101
101
 
102
102
  ```tsx
103
103
  <Klex activity="sleeping" size={40} />
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@klex/mascot",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "description": "The animated Klex mascot: a React component, its GSAP motion engine, body presets, and SVG helpers.",
5
5
  "type": "module",
6
6
  "license": "MIT AND CC-BY-4.0",
package/src/activity.ts CHANGED
@@ -153,6 +153,14 @@ export function createActivity() {
153
153
  laptop.snap(activity === 'working');
154
154
  book.snap(activity === 'learning');
155
155
  },
156
+ /**
157
+ * Takes an activity's pose at once; held props still spring in. Idle
158
+ * breathing starts from rest anyway, so it keeps its soft fade.
159
+ */
160
+ snapPose(activity: KlexActivity | false) {
161
+ for (const { id } of ACTIVITIES)
162
+ weights[id] = Number(activity === id && id !== 'idle');
163
+ },
156
164
  get workingBob() {
157
165
  const { laptopFloat, laptopTap } = working.pose();
158
166
  return (
package/src/glide.ts CHANGED
@@ -393,6 +393,10 @@ export function createGlide(
393
393
  let disposed = false;
394
394
  let height = flyingInitially ? 64 : 0;
395
395
  let activity: KlexActivity | false = false;
396
+ // Until a real activity has shown, the rig takes each pose at once, so it
397
+ // never animates out of its mount or a loading placeholder. Afterwards every
398
+ // change blends, e.g. eyes closing to sleep, including back to a placeholder.
399
+ let activityShown = false;
396
400
  const activityMotion = createActivity();
397
401
  let emote: { action: Emote; time: number } | null = null;
398
402
  let lastLook: EmoteLook = {};
@@ -958,6 +962,7 @@ export function createGlide(
958
962
  nextScale = 1,
959
963
  nextIdle = false,
960
964
  nextActivity: KlexActivity = 'idle',
965
+ activityPending = false,
961
966
  ) {
962
967
  hand = eyes.querySelector('[data-wave-anchor]');
963
968
  phone = eyes.querySelector('[data-phone-anchor]');
@@ -966,7 +971,12 @@ export function createGlide(
966
971
  settings = next;
967
972
  reducedMotion = reduced;
968
973
  activity = nextActivity === 'idle' && !nextIdle ? false : nextActivity;
974
+ if (!activityShown)
975
+ activityMotion.snapPose(
976
+ !busy && !transitioning && !emote ? activity : false,
977
+ );
969
978
  if (reduced) activityMotion.snapProps(activity);
979
+ if (!activityPending) activityShown = true;
970
980
  if (reduced && emote) {
971
981
  emote = null;
972
982
  onEmoteComplete();
package/src/klex.tsx CHANGED
@@ -94,8 +94,17 @@ export type KlexProps = {
94
94
  size?: number;
95
95
  /** Disable the default idle animation. Sleeping and working still animate. */
96
96
  idle?: boolean;
97
- /** Persistent resting animation. Resumes after travel and emotes. */
97
+ /**
98
+ * Persistent resting animation. Resumes after travel and emotes. A change
99
+ * blends in, e.g. eyes close to sleep; on mount it shows at once.
100
+ */
98
101
  activity?: KlexActivity;
102
+ /**
103
+ * Marks `activity` as a placeholder while the real one loads on mount. The
104
+ * first real activity shows at once instead of blending in; once one has
105
+ * shown, every change blends, including back to a placeholder.
106
+ */
107
+ activityPending?: boolean;
99
108
  /** Total track width. Defaults to size for a stationary avatar. */
100
109
  width?: CSSProperties['width'];
101
110
  /** Initial track position. Y is a pixel offset from the ground line. */
@@ -143,6 +152,7 @@ export function Klex({
143
152
  size = 160,
144
153
  idle = true,
145
154
  activity = 'idle',
155
+ activityPending = false,
146
156
  width = size,
147
157
  initialPosition,
148
158
  layout = 'track',
@@ -235,6 +245,7 @@ export function Klex({
235
245
  scale,
236
246
  idle,
237
247
  activity,
248
+ activityPending,
238
249
  );
239
250
  });
240
251
 
@@ -307,6 +318,7 @@ export function Klex({
307
318
  scale,
308
319
  idle,
309
320
  activity,
321
+ activityPending,
310
322
  );
311
323
  }, [
312
324
  reducedMotion,
@@ -314,6 +326,7 @@ export function Klex({
314
326
  scale,
315
327
  idle,
316
328
  activity,
329
+ activityPending,
317
330
  reactionLook.extra,
318
331
  extra,
319
332
  extrasEnabled,
@@ -334,6 +347,7 @@ export function Klex({
334
347
  scale,
335
348
  idle,
336
349
  activity,
350
+ activityPending,
337
351
  );
338
352
  }
339
353
  motion.moveTo(target === 'left' ? -50 : target === 'right' ? 50 : target);