svelte-stageshow 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benji Taylor
+
+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/NOTICE.md

@@ -0,0 +1,32 @@
+# Notices
+
+Stageshow source is MIT licensed; see `LICENSE`.
+
+The Svelte 5 port in this repository (`svelte-stageshow`, 2026) is by Ammar
+(maven-ammar). It keeps the original MIT licence and this notice. The ported
+components and the two gallery scenes come from the public Stageshow source in
+`benjitaylor/skills`; the original gold stills were filmed from that source and
+are kept in `shots/` for the parity record in the repository's `REHEARSAL.md`.
+
+Product and operating-system names, familiar device geometry, app icons, and
+illustrated interfaces are used as examples. Those names and marks remain
+with their owners; the Stageshow license does not grant trademark rights or
+imply endorsement. Adapt examples to the product you are illustrating.
+
+The Radix-inspired look uses publicly documented color and spacing values;
+its source is identified in `examples/looks/radix.css`. The app icons in `assets/app-icons.ts` are artwork from their respective app
+bundles, as identified in that file; they are not covered by the Stageshow MIT
+license. They remain illustrative references to those products. The Wikipedia
+study includes two local photographs dedicated under CC0 1.0 (also used
+in the Finder, Telegram and annotation studies); their authors,
+original source pages and modifications are recorded in
+[`examples/wikipedia/PHOTOS.md`](examples/wikipedia/PHOTOS.md). Other scenes
+use CSS and vector illustrations. No third-party fonts are bundled, and the
+playground does not fetch fonts or photographs from external services at runtime.
+
+The local brand registry in `kit/brands/` includes SVG artwork from SVGL (MIT), payment-icons (Apache 2.0), Cryptocurrency Icons (CC0 1.0), and official Linear, American Express and Circle assets. Per-file sources, hashes and license files are listed in [`kit/brands/SOURCES.md`](kit/brands/SOURCES.md). The original artwork and brand usage terms remain with their respective owners.
+
+`Phone frame="photo"` is optional. Supply your own permitted bezel image via
+`--ss-phone-photo-light: url(...)` and optionally `--ss-phone-photo-dark`.
+Without it, the kit uses its CSS-drawn `pro` frame. No bezel photographs are
+bundled.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# svelte-stageshow
 
-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.
+Svelte 5 port of Stageshow: framed faux product UI for stills and scripted
+demos. Stage, Window, Bar, Text, Row, Phone, Avatar and Chip; one CSS import;
+an Act scheduler with deterministic frame stepping.
+
+```sh
+pnpm add svelte-stageshow
+```
+
+```svelte
+<script lang="ts">
+  import { Avatar, Row, Stage, Window } from 'svelte-stageshow'
+  import 'svelte-stageshow/style.css'
+</script>
+
+<Stage width={640} height={320} className="my-stage">
+  {#snippet children(state, rect, layout)}
+    <Window title="Customers" className="my-window">
+      <Row selected title="Polaris Studio" subtitle="Scale · 24 seats">
+        {#snippet lead()}<Avatar name="Polaris Studio" size={30} tone="accent" />{/snippet}
+        {#snippet meta()}$12,400.00{/snippet}
+      </Row>
+    </Window>
+  {/snippet}
+</Stage>
+```
+
+The full README in the repository has the prop mapping (72 React prop names,
+0 missing), the diff table, the deterministic `runFrames()` contract and the
+verification record (`REHEARSAL.md`).
+
+- Intended repository: `maven-ammar/svelte-stageshow` (private, not pushed yet)
+- Licence: MIT, © 2026 Benji Taylor; Svelte port by Ammar (maven-ammar), 2026
+- Peer: `svelte` ^5. No React, react-dom or icon dependency.

package/dist/Avatar.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { getLook } from './look.js'
+
+  type Tone = 'accent' | 'ink' | 'success' | 'person' | 'ios'
+  type Ring = 'pending' | 'waiting' | 'confirmed' | 'declined'
+
+  interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, 'class'> {
+    /** Its initial. Leave it out (or set `plain`) for a plain disc. */
+    name?: string
+    /** A plain disc in any fidelity: filler people, so they don't compete with the named one. */
+    plain?: boolean
+    size?: number
+    tone?: Tone
+    src?: string
+    ring?: Ring
+    className?: string
+    /** Svelte's own class attribute; merged after className. */
+    class?: string
+    style?: string
+  }
+
+  let { name = '', plain = false, size = 24, tone, src, ring, className = '', class: klass = '', style = '', ...rest }: Props = $props()
+
+  // Six muted, opaque fills that read on light and dark grounds, one per person
+  const PEOPLE = ['#c98f6e', '#6f9b7d', '#7b86c7', '#c47a9e', '#8c9ab0', '#c2a35a']
+  const hue = (value: string) => {
+    let h = 0
+    for (const c of value) h = (h * 31 + c.charCodeAt(0)) % 9973
+    return PEOPLE[h % PEOPLE.length]
+  }
+
+  const look = getLook()
+  const disc = $derived(plain || look.fidelity === 'minimal')
+  const toneValue: Tone = $derived(tone ?? (name ? 'person' : 'ink'))
+  const person = $derived(toneValue === 'person' && !disc ? `background:${hue(name)};color:#fff;` : '')
+  const words = $derived(name.trim().split(/\s+/).filter(Boolean))
+  const initials = $derived(
+    toneValue === 'ios' ? (words[0]?.[0] ?? '') + (words.length > 1 ? words[words.length - 1]![0] : '') : (name.trim()[0] ?? ''),
+  )
+  const fontSize = $derived(Math.round(size * (toneValue === 'ios' ? 0.4 : size < 24 ? 0.5 : 0.42)))
+  const css = $derived(`width:${size}px;height:${size}px;font-size:${fontSize}px;${person}${style}`)
+</script>
+
+<span
+  {...rest}
+  class={`ss-avatar${className ? ` ${className}` : ''}${klass ? ` ${klass}` : ''}`}
+  data-tone={toneValue}
+  data-ring={ring}
+  style={css}
+>
+  {#if src && !disc}
+    <img {src} alt="" />
+  {:else if !disc}
+    <span class="ss-avatar__initial">{initials.toUpperCase()}</span>
+  {/if}
+</span>

package/dist/Avatar.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { HTMLAttributes } from 'svelte/elements';
+type Tone = 'accent' | 'ink' | 'success' | 'person' | 'ios';
+type Ring = 'pending' | 'waiting' | 'confirmed' | 'declined';
+interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, 'class'> {
+    /** Its initial. Leave it out (or set `plain`) for a plain disc. */
+    name?: string;
+    /** A plain disc in any fidelity: filler people, so they don't compete with the named one. */
+    plain?: boolean;
+    size?: number;
+    tone?: Tone;
+    src?: string;
+    ring?: Ring;
+    className?: string;
+    /** Svelte's own class attribute; merged after className. */
+    class?: string;
+    style?: string;
+}
+declare const Avatar: import("svelte").Component<Props, {}, "">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;

package/dist/Bar.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+  import type { HTMLAttributes } from 'svelte/elements'
+
+  interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, 'class'> {
+    /** Width in px, or any CSS length. */
+    w: number | string
+    h?: number
+    /** 1 (faintest) to 5. */
+    tone?: 1 | 2 | 3 | 4 | 5
+    r?: number
+    /** Let it narrow in a row too tight for it. On by default for a line. */
+    shrink?: boolean
+    className?: string
+    /** Svelte's own class attribute; merged after className. */
+    class?: string
+    style?: string
+  }
+
+  let { w, h = 6, tone = 3, r = 2, shrink, className = '', class: klass = '', style = '', ...rest }: Props = $props()
+
+  const INK = ['var(--ss-ink-1)', 'var(--ss-ink-2)', 'var(--ss-ink-3)', 'var(--ss-ink-4)', 'var(--ss-ink-5)'] as const
+  const gives = $derived(shrink ?? (typeof w === 'number' && w > h * 3))
+  const width = $derived(typeof w === 'number' ? `${w}px` : w)
+  const css = $derived(`width:${width};height:${h}px;border-radius:${r}px;background:${INK[tone - 1]};${style}`)
+</script>
+
+<span {...rest} class={`ss-bar${className ? ` ${className}` : ''}${klass ? ` ${klass}` : ''}`} data-shrink={gives || undefined} style={css}></span>

package/dist/Bar.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, 'class'> {
+    /** Width in px, or any CSS length. */
+    w: number | string;
+    h?: number;
+    /** 1 (faintest) to 5. */
+    tone?: 1 | 2 | 3 | 4 | 5;
+    r?: number;
+    /** Let it narrow in a row too tight for it. On by default for a line. */
+    shrink?: boolean;
+    className?: string;
+    /** Svelte's own class attribute; merged after className. */
+    class?: string;
+    style?: string;
+}
+declare const Bar: import("svelte").Component<Props, {}, "">;
+type Bar = ReturnType<typeof Bar>;
+export default Bar;

package/dist/Bubble.svelte

@@ -0,0 +1,255 @@
+<script lang="ts">
+  import { getContext, onDestroy, onMount, untrack } from 'svelte'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { getLook } from './look.js'
+  import { prefersReducedMotion, reducedMotion } from './reduced-motion.js'
+  import { THREAD_KEY, type ThreadContext } from './Thread.svelte'
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> {
+    /** me sits on the right in the accent bubble; them on the left. */
+    from: 'me' | 'them'
+    /** Three bouncing dots in place of the text. Turning it off grows the bubble into the message. */
+    typing?: boolean
+    /** Set by Thread: true on the last bubble of a run. */
+    tail?: boolean
+    /**
+     * Where the message comes from, as iMessage sends: a target name (or a
+     * CSS selector) for the composer's text. The bubble forms out of it, the
+     * words lifting from the field into place while the bubble fills in around
+     * them. Clear the field in the same update that adds the bubble.
+     */
+    source?: string
+    /**
+     * A tapback on this bubble: the emoji, and `show` to pop it in and out.
+     * It sits in a white circle on the bubble's bottom corner, and the bubble
+     * makes room below so the emoji never covers the words.
+     */
+    tapback?: { emoji: Snippet | string; show?: boolean }
+    /** A small `Avatar` beside a received bubble, as a group chat shows who is speaking. */
+    avatar?: Snippet
+    className?: string
+    /** Svelte's own class attribute; merged after className. */
+    class?: string
+    style?: string
+    /** Text, or a snippet for rich content. A string can also be passed to `children` directly. */
+    children?: Snippet | string
+  }
+
+  let {
+    avatar,
+    from,
+    typing = false,
+    tail,
+    source,
+    tapback,
+    className = '',
+    class: klass = '',
+    style = '',
+    children,
+    ...rest
+  }: Props = $props()
+
+  const { fidelity } = getLook()
+  const thread = getContext<ThreadContext | undefined>(THREAD_KEY)
+  // Bubbles in the thread on its first render are the opening picture and
+  // don't animate; only later arrivals rise in.
+  const arrived = thread ? thread.ready : true
+
+  let rowEl = $state<HTMLDivElement | null>(null)
+  let bubbleEl = $state<HTMLDivElement | null>(null)
+  let autoTail = $state<boolean | undefined>(undefined)
+  const effectiveTail = $derived(tail !== undefined ? tail : autoTail)
+
+  onMount(() => {
+    if (!thread) return
+    return thread.register({
+      row: () => rowEl,
+      from: () => from,
+      explicit: () => tail !== undefined,
+      setTail: (value) => {
+        autoTail = value
+      },
+    })
+  })
+
+  // Whether this bubble grew out of the typing dots (its words fade in as it
+  // grows). The flag latches on, as the React ref did.
+  let lastTyping = $state(untrack(() => typing))
+  let grew = $state(false)
+  $effect.pre(() => {
+    if (lastTyping && !typing) grew = true
+    lastTyping = typing
+  })
+
+  // Morph: measure the bubble before and after the content changes, then ease
+  // its box from the old size to the new.
+  let size: { w: number; h: number } | null = null
+  let animating = false
+  let morphTimer: ReturnType<typeof setTimeout> | null = null
+
+  function measure(node: HTMLElement) {
+    const measured = getComputedStyle(node)
+    return { w: parseFloat(measured.width), h: parseFloat(measured.height) }
+  }
+
+  function morph() {
+    const el = bubbleEl
+    if (!el || animating) return
+    const was = size
+    el.style.width = ''
+    el.style.height = ''
+    // Resolved CSS dimensions retain the fractions offsetWidth/Height round
+    // away, so releasing the measured box doesn't resize it at the endpoint.
+    const now = measure(el)
+    size = now
+    if (!was || (was.w === now.w && was.h === now.h)) return
+    if (reducedMotion(el)) return
+    animating = true
+    // The words keep their final line breaks while the box grows around them
+    const text = el.querySelector<HTMLElement>('.ss-bubble__text')
+    if (text) text.style.width = getComputedStyle(text).width
+    el.style.transition = 'none'
+    el.style.width = `${was.w}px`
+    el.style.height = `${was.h}px`
+    void el.offsetWidth
+    el.style.transition = ''
+    el.style.width = `${now.w}px`
+    el.style.height = `${now.h}px`
+    const end = () => {
+      if (morphTimer) {
+        clearTimeout(morphTimer)
+        morphTimer = null
+      }
+      el.removeEventListener('transitionend', end)
+      el.style.width = ''
+      el.style.height = ''
+      if (text) text.style.width = ''
+      animating = false
+      size = measure(el)
+    }
+    el.addEventListener('transitionend', end, { once: true })
+    // Reduced motion or a stage still can remove the transition entirely, so a
+    // timer releases the measured box even if transitionend never arrives.
+    morphTimer = setTimeout(end, 600)
+  }
+
+  $effect(() => {
+    void typing
+    void children
+    morph()
+  })
+
+  $effect(() => {
+    const el = bubbleEl
+    if (!el) return
+    size = measure(el)
+    const ro = new ResizeObserver(() => morph())
+    ro.observe(el)
+    return () => ro.disconnect()
+  })
+
+  onDestroy(() => {
+    if (morphTimer) clearTimeout(morphTimer)
+  })
+
+  // Form out of the composer: start where the field's words were, in the
+  // field's color with no fill, and travel into place as the fill comes in.
+  $effect(() => {
+    const el = bubbleEl
+    if (!el || !arrived || !source) return
+    const stage = el.closest('.ss-stage') ?? document
+    const src =
+      stage.querySelector<HTMLElement>(`[data-target="${source}"]`) ?? stage.querySelector<HTMLElement>(source)
+    const text = el.querySelector<HTMLElement>('.ss-bubble__text')
+    if (!src || !text) return
+    if (prefersReducedMotion() || el.closest('[data-still]')) return
+    // Measure where it rests, not where an earlier run already moved it
+    el.style.transition = 'none'
+    el.style.left = el.style.top = '0px'
+    const k = el.getBoundingClientRect().width / el.offsetWidth || 1
+    const o = src.getBoundingClientRect()
+    const t = text.getBoundingClientRect()
+    const dx = (o.left - t.left) / k
+    const dy = (o.top + o.height / 2 - (t.top + t.height / 2)) / k
+    const ease = 'cubic-bezier(0.22, 1, 0.36, 1)'
+    // Travels by left and top, so the words land without a sub-pixel hop
+    el.style.transition = 'none'
+    el.style.left = `${dx}px`
+    el.style.top = `${dy}px`
+    el.setAttribute('data-flying', '')
+    el.style.color = getComputedStyle(src).color
+    void el.offsetWidth
+    el.style.transition = `left 0.5s ${ease}, top 0.5s ${ease}, color 0.3s ease 0.06s`
+    el.style.left = el.style.top = ''
+    el.removeAttribute('data-flying')
+    el.style.color = ''
+    const end = (e: TransitionEvent) => {
+      if (e.target !== el || e.propertyName !== 'top') return
+      el.style.transition = ''
+      el.removeEventListener('transitionend', end)
+    }
+    el.addEventListener('transitionend', end)
+    return () => el.removeEventListener('transitionend', end)
+  })
+
+  const isBar = $derived(fidelity === 'minimal' && typeof children === 'string')
+  const barWidth = $derived(typeof children === 'string' ? Math.min(180, children.length * 5.5) : 0)
+</script>
+
+<div
+  class={`ss-bubble-row${className ? ` ${className}` : ''}${klass ? ` ${klass}` : ''}`}
+  data-from={from}
+  data-avatar={avatar ? '' : undefined}
+  style={style || undefined}
+  bind:this={rowEl}
+>
+  {#if avatar && from !== 'me'}
+    <span class="ss-bubble__avatar" aria-hidden="true">{@render avatar()}</span>
+  {/if}
+  <div
+    {...rest}
+    bind:this={bubbleEl}
+    class="ss-bubble"
+    data-arrived={arrived || undefined}
+    data-source={source ? '' : undefined}
+    data-tail={effectiveTail || undefined}
+    data-typing={typing || undefined}
+    data-grew={grew || undefined}
+    data-tapback={tapback && tapback.show !== false ? '' : undefined}
+  >
+    {#if tapback}
+      <span class="ss-tapback" data-show={tapback.show !== false || undefined} aria-hidden="true">
+        <span class="ss-tapback__emoji">
+          {#if typeof tapback.emoji === 'string'}{tapback.emoji}{:else}{@render tapback.emoji()}{/if}
+        </span>
+      </span>
+    {/if}
+    {#if typing}
+      <span class="ss-bubble__dots" aria-label="typing">
+        <i></i>
+        <i></i>
+        <i></i>
+      </span>
+    {:else}
+      <span class="ss-bubble__text">
+        {#if isBar}
+          <span class="ss-bar ss-bubble__bar" style={`width:${barWidth}px`}></span>
+        {:else if typeof children === 'string'}
+          {children}
+        {:else if children}
+          {@render children()}
+        {/if}
+      </span>
+    {/if}
+    <!-- Always drawn, so a tail grows out of the corner when its bubble
+         becomes the last of a run, and retracts when it stops being. -->
+    <svg class="ss-bubble__tail" viewBox="0 0 18 16" aria-hidden="true">
+      <path
+        d={from === 'me'
+          ? 'M0 0H12V8.5C12 12.6 14 15 17.5 16C15 16.7 12.2 16.5 9.8 15.3L0 15Z'
+          : 'M18 0H6V8.5C6 12.6 4 15 0.5 16C3 16.7 5.8 16.5 8.2 15.3L18 15Z'}
+      />
+    </svg>
+  </div>
+</div>

package/dist/Bubble.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> {
+    /** me sits on the right in the accent bubble; them on the left. */
+    from: 'me' | 'them';
+    /** Three bouncing dots in place of the text. Turning it off grows the bubble into the message. */
+    typing?: boolean;
+    /** Set by Thread: true on the last bubble of a run. */
+    tail?: boolean;
+    /**
+     * Where the message comes from, as iMessage sends: a target name (or a
+     * CSS selector) for the composer's text. The bubble forms out of it, the
+     * words lifting from the field into place while the bubble fills in around
+     * them. Clear the field in the same update that adds the bubble.
+     */
+    source?: string;
+    /**
+     * A tapback on this bubble: the emoji, and `show` to pop it in and out.
+     * It sits in a white circle on the bubble's bottom corner, and the bubble
+     * makes room below so the emoji never covers the words.
+     */
+    tapback?: {
+        emoji: Snippet | string;
+        show?: boolean;
+    };
+    /** A small `Avatar` beside a received bubble, as a group chat shows who is speaking. */
+    avatar?: Snippet;
+    className?: string;
+    /** Svelte's own class attribute; merged after className. */
+    class?: string;
+    style?: string;
+    /** Text, or a snippet for rich content. A string can also be passed to `children` directly. */
+    children?: Snippet | string;
+}
+declare const Bubble: import("svelte").Component<Props, {}, "">;
+type Bubble = ReturnType<typeof Bubble>;
+export default Bubble;

package/dist/Caret.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  interface Props {
+    /** While typing, a real terminal holds the cursor solid. */
+    still?: boolean
+  }
+
+  let { still = false }: Props = $props()
+</script>
+
+<span class="ss-term__caret" data-still={still || undefined} aria-hidden="true"></span>

package/dist/Caret.svelte.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    /** While typing, a real terminal holds the cursor solid. */
+    still?: boolean;
+}
+declare const Caret: import("svelte").Component<Props, {}, "">;
+type Caret = ReturnType<typeof Caret>;
+export default Caret;