# Buddy launch day — Claude integration

This optional module introduces the **original Buddy**, with his existing fixed-size shell and articulated animation limbs. The later robot redesign concepts are not used.

Open `launch-preview.html` to play the full sequence or try individual effects. Nothing launches automatically, publishes anything, or changes app data.

## Install

Copy the complete `buddy-library` folder from the local package. Load the usual runtime scripts in their documented order, then load `buddy-library/launch-day.js`. The release bundle already includes it. Create the scene only after scripts load.

```js
const launch = new BuddyLaunch({
  celebrationDuration: 30, // seconds of replenishing effects, starting at the snip
  size: 240, // explicit character size; never automatically resized
  greeting: "I'm so excited!",
  returnLine: 'Well… that was one way to make an entrance.',
  welcomeLine: "Hi, I'm Buddy. Let's get started!",
  // reducedMotion: true, // otherwise honours the system preference
});

launch.addEventListener('cut', () => {
  // Optional: update your launch-page heading here.
});
const { cancelled } = await launch.start();
// At completion Buddy remains standing at exactly his final position.
// Keep him on screen until your app is ready, then:
// launch.destroy();
```

`start()` returns a promise resolving after `Math.max(14, 5.6 + celebrationDuration)` active seconds, or immediately on cancellation as `{cancelled: true}`. Restarting cancels the old run. `cancel()` / `destroy()` remove the owned Buddy, ribbon, speech, effects and listeners. Call `destroy()` on route unmount. The module owns a separate Buddy instance: pause and hide your app's ordinary Buddy during the introduction, then restore it when you dismiss the stage. Do not call movement APIs on `launch.buddy`; it is controlled by the scene. No speech audio is included: lines appear in an accessible live text bubble.

The overlay uses viewport coordinates, fixed layers 10000–10002 and pointer-transparent art, so app controls remain usable. Include a visible Skip/Close button that calls `launch.cancel()`. This launch is intentionally opt-in; the app decides when to show it and whether to persist a “seen introduction” flag. Do not automatically mark launch business tasks complete from an animation event.

## Timeline and mechanics

Buddy’s performance stays 14 seconds long. Effects run for `celebrationDuration` seconds from the cut (default 8.4). A longer value keeps Buddy in his final standing pose while fresh confetti, stars, balloons and particles keep coming; it does not slow his actions. Any positive finite duration is accepted; invalid values fall back to 8.4 seconds. `effects.duration` is also supported when `celebrationDuration` is omitted. The `introduced` event fires at 14 seconds; `complete` and the promise wait until both the introduction and effects are finished. `launch.duration` exposes the calculated total.

| Active seconds | Beat |
| --- | --- |
| 0–1.8 | Walks in from the left, supported on a common invisible stage floor; turns from profile to face the audience. |
| 1.8–4.6 | Pauses and says “I'm so excited!” |
| 4.6–5.6 | Lifts his wrist-held scissors, opens the two hinged halves, focuses and squeezes the handle rings closed on the ribbon. Thumb and fingers remain through the rings. |
| 5.6–6.05 | Ribbon halves recoil sideways. Left cut end curls back towards his wrist. Celebration begins. |
| 6.05–6.85 | Visible loop catches his wrist; tension accelerates him left. His body rises then falls along a gravity-shaped arc, with tucked legs. Scissors stay attached to his other hand. |
| 6.85–7.6 | Briefly off-screen. Props are put away while hidden. |
| 7.6–9.5 | Walks back in; blush appears. |
| 9.5–12.6 | Embarrassed lean and line, with soles remaining on the floor. |
| 12.6–14 | Faces forward with a welcome line. Final body and foot coordinates are retained. Effects continue until the configured duration expires, then fade. |

`BuddyLaunch.timings` exposes these beat times. Events: `greeting`, `cut`, `catch`, `return`, `introduced`, `complete`. System reduced motion uses a stationary ribbon reveal and static fading decorations, preserving the greeting and welcome without the yank; it omits `catch`/`return` events. An OS motion preference change cancels the current scene. Background tabs pause the active-time clock. Window resizing repositions the stage without changing Buddy's physical size.

## Independent celebration effects

```js
const effects = BuddyLaunch.celebrate({
  types: ['confetti', 'stars', 'balloons', 'particles'],
  duration: 30, // any positive finite number of seconds
  // reducedMotion: true,
  // zIndex: 10002,
});
// Automatically removed at the end; cancel early on navigation:
effects.destroy();
```

Each type works alone or in a combination. Confetti, golden stars and colourful particles burst upward then descend under gravity; balloons rise with gentle drift. Effects use a bounded particle count and a canvas capped at 2× screen pixel density. They require no network requests, assets, permissions or audio. Under reduced motion the decorations stay still and fade. The full scene accepts an `effects` object for `types`, `seed`, `zIndex` and `duration`. A top-level `celebrationDuration` takes precedence over `effects.duration`. Particles recycle on staggered lifetimes rather than stretching the original burst, so long celebrations remain lively with a constant memory footprint.

## Review and limitations

Tested: 390px and 768px layouts, exact shell scale, sole support, continuous wrist catch and ending, reduced motion, repeated starts, cancellation and DOM cleanup. Verified blade/ribbon alignment, handle grip continuity, and continuing effects at 25/40/65 seconds. Reviewed the full normal-speed sequence and sampled cut, catch, flight and recovery poses. This is a self-contained viewport stage, not a collision system for arbitrary app controls. It is designed for an introductory page with a clear lower area. At unusually small viewport heights or deliberately large caller sizes, the caller must choose a suitable explicit size/layout.

Standing animation rules are included in `AGENTS.md`; preserve them when revising this sequence.

The ribbon uses a smooth filled red satin strip with broad reflections and gently curved edges. Its cut ends twist into folds during recoil, without repeated diagonal crease marks. Buddy’s arm, hand and scissors remain behind the fabric, with blade tips emerging visibly above it. He aligns them nearly upright, opens at 4.72–5.02s, holds, and squeezes at 5.22–5.60s. Each cut half starts at the same curve it occupied before the snip.


### Gentle ribbon breeze — v0.26.3

Before the snip, the satin ribbon carries a subtle left-to-right ripple (up to 6px). The screen-edge supports and scissor contact remain steady. Recoil starts from the exact ribbon shape at the cut. Reduced motion disables the breeze. The 14-second performance, 5.6-second snip and configurable celebration duration are unchanged.


### Grand celebration — v0.26.4

The default celebration now combines twin side confetti cannons, an overhead confetti shower, curling streamers, glowing golden stars, three colourful sparkle-burst origins and fuller glossy balloon waves. A fixed pool of 708 pieces recycles for the configured duration (360 confetti/streamers, 100 stars, 220 sparkles, 28 balloons). Reduced motion retains static fading decorations at substantially lower density. Scene timings and the configurable duration API are unchanged.


## Optional portal launch — v0.27.2

The classic entrance remains available as `variant: 'classic'` and is still the API default. The preview defaults to `variant: 'portal'`; use its Entrance selector to compare.

```js
const launch = new BuddyLaunch({
  variant: 'portal', // or 'classic' for the preserved entrance
  size: 240,
  celebrationDuration: 30,
});
await launch.start();
```

The portal uses the same purple gate, cyan dashed swirl and sparkle artwork as `enter_portal` / `exit_portal` in transitions.js, rotated and foreshortened into a downward-facing ceiling opening. The scissors sit farther right; travel distance is clamped to keep the tool on screen without resizing Buddy.

Buddy drops face-up in profile onto a pastel sticky-note pile. His back meets the pile, the paper compresses under him, and 24 notes scatter upwards before gliding down with independent flutter and fading away. He braces a palm, rolls upright, plants both soles, then gives a quick shake. The shell stays rigid throughout. Reduced motion skips the fall, scatter and shake.

| Seconds | Portal sequence |
| --- | --- |
| 0–0.55 | Portal opens overhead; sticky-note pile waits below |
| 0.55–1.5 | Accelerating face-up fall |
| 1.5–2.1 | Back lands on the paper pile; notes burst upwards; brief dazed pause |
| 2.1–3.75 | Braces with a hand and gets up |
| 3.85–4.5 | Quick shake with feet planted |
| 5.05–5.4 | Spots the scissors |
| 5.4–6.6 | Walks right to the scissors |
| 6.8–7.5 | Crouches and reaches; grasps at 7.5s |
| 7.8–8.6 | Stands, lifting the attached scissors |
| 8.6–9.8 | Confused glances |
| 9.8–11.4 | Faces left and walks back to his original middle position |
| 11.4–12.8 | Settles and recognises the ribbon |
| 12.8 | Greeting |
| 16.6 | Cut |
| 17.05 | Wrist catch |
| 18.6 | Embarrassed return begins |
| 23.6 | Final welcome |
| 25 | Introduction finished |

`BuddyLaunch.portalTimings` exposes these timings. `BuddyLaunch.timings` retains the classic timings. All classic post-entrance beats shift by eleven seconds in the portal variant. Portal total completion is `max(25, 16.6 + celebrationDuration)`; `introduced` fires at 25s. Event times include the offset.

Scissors stay fixed until grasp, then share the wrist position throughout lifting and walking. Buddy keeps his shell size, floor contacts and final world position. Reduced motion omits the aerial drop and side travel, placing the scissors within reach. Cancellation, replay and configurable celebrations work with either entrance.
