@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/steps-with-media.gts

@@ -0,0 +1,254 @@
+// Pretui — StepsWithMedia: a step list whose active step shows its media.
+import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
+import { StepList } from './step-list';
+import type { StepItem, StepListVariant } from './step-list';
+import { MediaViewer } from './media-viewer';
+import type { MediaAssetSpec } from '../internal/media-viewer';
+import { cssStyle } from '../pretui-css';
+import { ariaLevelFor } from '../internal/blocks';
+import type { BlockHeadingLevel } from '../internal/blocks';
+
+// ═════════════════════════════════════════════════════════════════════════
+// B3 · StepsWithMedia
+// ═════════════════════════════════════════════════════════════════════════
+//
+// From catalog-app's storefront-how-it-works: a framed media panel beside a
+// numbered list of steps.
+//
+// THE MEDIA IS A STATIC COLUMN, NOT A PER-STEP SWITCHER, and the reason is
+// the tier definition rather than taste. Per-step switching needs a
+// selected index, a keyboard path across the steps, focus management and an
+// announcement when the panel changes — that is a state machine, which
+// makes it a COMPONENT, not a block. A block that quietly grew one would be
+// exactly the failure this tier exists to prevent.
+//
+// The caller keeps the ability anyway, and keeps it correctly: `@current`
+// and `@asset` are both args, so a host that already owns a selected index
+// passes a different asset alongside a different `@current` and gets
+// per-step media with the state living where state belongs. That is the
+// controlled pattern, and it costs this block nothing.
+//
+// Step semantics are NOT reimplemented. `StepList` (controls-composites)
+// already owns the <ol>/<li>, the numbered markers, six states with a
+// glyph each, per-step detail lines, the completion summary wired with
+// aria-describedby, the polite live region, and its own container-query
+// responsive behaviour. This block passes `@steps`, `@current`, `@variant`
+// and `@summary` straight through and adds nothing but the column.
+//
+// BETTER THAN THE INSPIRATION:
+//   · `STEPS` was a module-level const, so the block was welded to one
+//     product → steps are an arg, typed as StepList's own `StepItem`, so
+//     they gain state, detail lines and the summary for free.
+//   · The framed asset was an AUTOPLAYING GIF that could not be paused and
+//     ignored `prefers-reduced-motion`, with no static poster — the file's
+//     worst defect → the asset goes through `MediaViewer`, which routes a
+//     video to the kit's player (transport, captions, keyboard, no
+//     autoplay) and an image to a frame that reserves its ratio.
+//   · `@ts-expect-error` on the asset import → the asset is data.
+//   · A container query collapsing to one column: KEPT, and kept unnamed.
+//
+// No browser-chrome frame around the screenshot, deliberately: that is a
+// visual treatment, not part of a steps block, and the source's version
+// hardcoded its traffic-light colours and read three meaningless dots to a
+// screen reader. A caller who wants one puts it in the `<:media>` block.
+
+export interface StepsWithMediaSignature {
+  Args: {
+    /** Small line above the title. */
+    eyebrow?: string;
+    /** Section title. */
+    title?: string;
+    /** One paragraph under the title. */
+    lead?: string;
+    /** The steps, handed straight to StepList. */
+    steps: readonly StepItem[];
+    /** Index of the current step — StepList derives
+     * complete/current/upcoming for steps without an explicit state. */
+    current?: number;
+    /** StepList presentation: `steps` (numbered rail) or `track`. */
+    variant?: StepListVariant;
+    /** Show StepList's derived completion summary. */
+    summary?: boolean;
+    /** Accessible name for the step list. Defaults to the title. */
+    stepsLabel?: string;
+    /** The media panel's asset. Routed by MediaViewer. */
+    asset?: MediaAssetSpec;
+    /** Which side the media sits on VISUALLY at wide widths. Source order
+     * is always content-first. Default `start`, matching the source. */
+    mediaSide?: 'start' | 'end';
+    /** Hold the media panel at a fixed CSS `aspect-ratio`. */
+    ratio?: string;
+    /** Heading level for the title in the host page. */
+    headingLevel?: BlockHeadingLevel;
+  };
+  Blocks: {
+    /** Replaces the media panel — a BrowserFrame, a Chart, a Scene. */
+    media: [];
+    /** Anything under the step list. */
+    default: [];
+  };
+  Element: HTMLElement;
+}
+
+export class StepsWithMedia extends Component<StepsWithMediaSignature> {
+  private titleId = guidFor(this) + '-title';
+
+  get mediaSide(): 'start' | 'end' {
+    return this.args.mediaSide === 'end' ? 'end' : 'start';
+  }
+  get headingAriaLevel() {
+    return ariaLevelFor(this.args.headingLevel);
+  }
+  get style() {
+    return cssStyle('--pretui-swm-ratio', this.args.ratio);
+  }
+  get ratioMode(): string {
+    return this.args.ratio ? 'fixed' : 'intrinsic';
+  }
+  get steps(): StepItem[] {
+    return [...(this.args.steps ?? [])];
+  }
+  get stepsLabel(): string {
+    return this.args.stepsLabel ?? this.args.title ?? 'Steps';
+  }
+  get labelledBy() {
+    return this.args.title ? this.titleId : undefined;
+  }
+
+  <template>
+    <section
+      class='pretui-swm'
+      style={{this.style}}
+      data-media-side={{this.mediaSide}}
+      aria-labelledby={{this.labelledBy}}
+      data-test-pretui-steps-with-media
+      ...attributes
+    >
+      <div class='pretui-swm-grid'>
+        <div class='pretui-swm-content'>
+          {{#if @eyebrow}}
+            <p class='pretui-swm-eyebrow'>{{@eyebrow}}</p>
+          {{/if}}
+          {{#if @title}}
+            <h2
+              id={{this.titleId}}
+              class='pretui-swm-title'
+              aria-level={{this.headingAriaLevel}}
+            >{{@title}}</h2>
+          {{/if}}
+          {{#if @lead}}
+            <p class='pretui-swm-lead'>{{@lead}}</p>
+          {{/if}}
+          <StepList
+            @steps={{this.steps}}
+            @current={{@current}}
+            @variant={{@variant}}
+            @summary={{@summary}}
+            @label={{this.stepsLabel}}
+            data-test-pretui-swm-steps
+          />
+          {{yield}}
+        </div>
+
+        {{#if (has-block 'media')}}
+          <div
+            class='pretui-swm-media'
+            data-ratio={{this.ratioMode}}
+            data-test-pretui-swm-media
+          >{{yield to='media'}}</div>
+        {{else}}
+          {{! see the note in HeroSplit — else-if does not narrow @asset }}
+          {{#if @asset}}
+            <div
+              class='pretui-swm-media'
+              data-ratio={{this.ratioMode}}
+              data-test-pretui-swm-media
+            >
+              <MediaViewer @asset={{@asset}} />
+            </div>
+          {{/if}}
+        {{/if}}
+      </div>
+    </section>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-swm {
+          container-type: inline-size;
+          display: block;
+        }
+        .pretui-swm-grid {
+          display: grid;
+          grid-template-columns:
+            minmax(0, var(--pretui-swm-content-fr, 1fr))
+            minmax(0, var(--pretui-swm-media-fr, 1fr));
+          gap: var(--pretui-swm-gap, var(--space-8, 34px));
+          align-items: start;
+        }
+        .pretui-swm[data-media-side='start'] .pretui-swm-media {
+          order: -1;
+        }
+        .pretui-swm-content {
+          display: grid;
+          gap: var(--space-4, 11px);
+          align-content: start;
+          min-width: 0;
+        }
+        .pretui-swm-eyebrow {
+          margin: 0;
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-xs, 11px);
+          font-weight: 500;
+          letter-spacing: var(--track-eyebrow, 0.08em);
+          text-transform: uppercase;
+          color: var(--muted-foreground);
+        }
+        .pretui-swm-title {
+          margin: 0;
+          font-family: var(--font-serif);
+          font-size: var(--pretui-swm-title-size, var(--text-heading, 19px));
+          font-weight: 400;
+          line-height: 1.2;
+          letter-spacing: var(--track-heading, -0.02em);
+          color: var(--foreground);
+          text-wrap: balance;
+        }
+        .pretui-swm-lead {
+          margin: 0;
+          font-size: var(--text-body, 15px);
+          line-height: 1.5;
+          color: var(--muted-foreground);
+          max-width: 58ch;
+        }
+        .pretui-swm-media {
+          min-width: 0;
+          position: sticky;
+          top: var(--pretui-swm-sticky-top, 0);
+        }
+        .pretui-swm-media[data-ratio='fixed'] {
+          aspect-ratio: var(--pretui-swm-ratio, 16 / 9);
+          overflow: hidden;
+          display: grid;
+          place-items: center;
+          border-radius: var(--radius-surface, 10px);
+        }
+
+        @container (max-width: 46rem) {
+          .pretui-swm-grid {
+            grid-template-columns: minmax(0, 1fr);
+            gap: var(--pretui-swm-gap-narrow, var(--space-5, 14px));
+          }
+          .pretui-swm[data-media-side='start'] .pretui-swm-media {
+            order: 0;
+          }
+          /* Sticky is a wide-column affordance. In one column it would pin
+             the picture over the steps you are trying to read. */
+          .pretui-swm-media {
+            position: static;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/steps-with-media.md

@@ -0,0 +1,54 @@
+## What it is
+
+A marketing-page block pairing a numbered step list with a media panel: eyebrow, title, lead, steps on one side, a picture or a live component on the other.
+
+## The contract
+
+```
+@eyebrow?, @title?, @lead? — the heading stack
+@steps (required) — handed straight to StepList
+@current?     — index of the current step; StepList derives complete / current /
+                upcoming for steps without an explicit state
+@variant?     — StepList presentation: 'steps' (numbered rail) or 'track'
+@summary?     — show StepList's derived completion summary
+@stepsLabel?  — accessible name for the step list. Defaults to the title
+@asset?       — the media panel's asset; routed by MediaViewer
+@mediaSide?   — which side the media sits on VISUALLY at wide widths. Default 'start'
+@ratio?       — hold the media panel at a fixed CSS aspect-ratio
+@headingLevel? — heading level for the title in the host page
+
+<:media>   — replaces the media panel: a BrowserFrame, a Chart, a Scene
+<:default> — anything under the step list
+```
+
+**`@mediaSide` moves the media visually and never in source order.** Source order is always content-first, so the reading order is the same whichever side the picture is on. A block that reordered the DOM to move a picture would change what a screen reader encounters first based on a visual preference.
+
+**`@headingLevel` exists because a block does not know its page.** A section title that is an `<h2>` on one page and an `<h3>` on another is the caller's decision, and hardcoding it is how document outlines break.
+
+**The media panel routes through MediaViewer**, so an `@asset` of any kind renders correctly; `<:media>` replaces the panel entirely for anything that is not an asset.
+
+**`@ratio` reserves the panel** so the block does not reflow when the media lands.
+
+## Prior art
+
+The "how it works" section every marketing page builds by hand.
+
+Where Pretui is better: the visual/source-order split, the heading level as an argument, and the steps being a real **StepList** rather than a styled `<ol>` — so state derivation, the completion summary and the list's own accessibility come along.
+
+Where it is thinner: one media panel and one step list, no alternating layout across several instances (the caller alternates `@mediaSide`), and no scroll-linked step advancement.
+
+## Accessibility
+
+- **Source order is content-first regardless of `@mediaSide`**, which is the block's most important property: visual arrangement and reading order are decided separately.
+- **`@headingLevel` keeps the document outline correct** in whatever page the block lands in.
+- **`@stepsLabel` names the step list**, defaulting to the title so it is never anonymous.
+- **The step semantics are StepList's** — complete, current and upcoming are conveyed there rather than by position or colour here.
+- **The media is decoration unless the asset says otherwise.** An `@asset` carries its own alt text through MediaViewer; a `<:media>` block owns its own.
+
+## Theming
+
+The block composes **StepList** and **MediaViewer** and takes the kit's shared block spacing and heading tokens rather than defining its own surface.
+
+That is the right shape for a Block-tier component: it is an arrangement of other components, and a theme retunes it by retuning them — a block with its own type scale would drift away from the sections above and below it on the same page.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/steps-with-media.usage.gts

@@ -0,0 +1,208 @@
+// Pretui — StepsWithMedia usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import type { StepItem, StepListVariant } from './step-list';
+import type { MediaAssetSpec } from '../internal/media-viewer';
+import { platePoster } from '../media-examples';
+import { StepsWithMedia } from './steps-with-media';
+
+// ── Fixtures ─────────────────────────────────────────────────────────────
+const STEPS_ASSET: MediaAssetSpec = {
+  src: platePoster('Lot workspace', '16 / 9'),
+  name: 'Lot workspace',
+  mimeType: 'image/svg+xml',
+  kind: 'image',
+  alt: 'A generated stand-in screenshot of the lot workspace',
+  width: 1600,
+  height: 900,
+};
+
+const HOW_STEPS: readonly StepItem[] = [
+  {
+    label: 'Open a lot',
+    detail: 'Every lot arrives with its origin, grade and moisture already read.',
+  },
+  {
+    label: 'Set your ceiling',
+    detail: 'One number. The floor bids against it for you.',
+  },
+  {
+    label: 'Watch the board',
+    detail: 'Live positions, with your ceiling marked on every line.',
+  },
+  {
+    label: 'Settle',
+    detail: 'Contract, invoice and manifest are generated from the winning bid.',
+  },
+];
+
+// ═════════════════════════════════════════════════════════════════════════
+// ReadinessPanel
+// ═════════════════════════════════════════════════════════════════════════
+
+class StepsWithMediaUsage extends Component {
+  @tracked eyebrow = 'How the floor works';
+  @tracked title = 'Four steps from sample to settlement';
+  @tracked lead =
+    'The same four steps every lot goes through, whether it is a single chest or a whole season.';
+  @tracked current = 2;
+  @tracked variant = 'steps';
+  @tracked summary = true;
+  @tracked mediaSide = 'start';
+
+  setEyebrow = (v: string) => (this.eyebrow = v);
+  setTitle = (v: string) => (this.title = v);
+  setLead = (v: string) => (this.lead = v);
+  setCurrent = (v: number) => (this.current = v);
+  setVariant = (v: string) => (this.variant = v);
+  setSummary = (v: boolean) => (this.summary = v);
+  setMediaSide = (v: string) => (this.mediaSide = v);
+
+  get variantOptions(): string[] {
+    return ['steps', 'track'];
+  }
+  get sideOptions(): string[] {
+    return ['start', 'end'];
+  }
+  get railVariant(): StepListVariant {
+    return this.variant === 'track' ? 'track' : 'steps';
+  }
+  get side(): 'start' | 'end' {
+    return this.mediaSide === 'end' ? 'end' : 'start';
+  }
+  get steps(): StepItem[] {
+    return [...HOW_STEPS];
+  }
+  get asset(): MediaAssetSpec {
+    return STEPS_ASSET;
+  }
+
+  get usage(): string {
+    return (
+      '<StepsWithMedia\n' +
+      "  @title='" +
+      this.title +
+      "'\n" +
+      '  @steps={{this.steps}}\n' +
+      '  @current={{this.current}}\n' +
+      '  @asset={{this.asset}}\n' +
+      '/>'
+    );
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='StepsWithMedia'
+      @description='A block: steps paired with a media panel. Composes StepList (the whole ordered list — markers, six states, per-step detail lines, the derived completion summary, the polite live region) and MediaViewer (the panel). Step semantics are not reimplemented here; this block contributes the column and nothing else. The media is a STATIC column on purpose: per-step switching needs a selected index, a keyboard path and an announcement, which is a state machine and therefore a component. A caller who already owns a selected index passes a different asset alongside a different current and gets per-step media with the state living where state belongs.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <StepsWithMedia
+          @eyebrow={{this.eyebrow}}
+          @title={{this.title}}
+          @lead={{this.lead}}
+          @steps={{this.steps}}
+          @current={{this.current}}
+          @variant={{this.railVariant}}
+          @summary={{this.summary}}
+          @asset={{this.asset}}
+          @mediaSide={{this.side}}
+          @ratio='16 / 9'
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Array
+          @name='steps'
+          @description='The steps, handed straight to StepList. Each is label plus an optional state and detail line, so a step can say it is blocked and why.'
+        />
+        <Args.Number
+          @name='current'
+          @value={{this.current}}
+          @min={{-1}}
+          @max={{3}}
+          @description='Index of the current step. StepList derives complete, current and upcoming for every step without an explicit state.'
+          @onInput={{this.setCurrent}}
+        />
+        <Args.String
+          @name='variant'
+          @value={{this.variant}}
+          @defaultValue='steps'
+          @options={{this.variantOptions}}
+          @description='StepList presentation. steps is the numbered rail; track is the segmented bar read at a glance.'
+          @onInput={{this.setVariant}}
+        />
+        <Args.Bool
+          @name='summary'
+          @value={{this.summary}}
+          @defaultValue={{false}}
+          @description='Show the derived completion count, wired to the list with aria-describedby.'
+          @onInput={{this.setSummary}}
+        />
+        <Args.String
+          @name='title'
+          @value={{this.title}}
+          @description='Section title, and the block accessible name when present.'
+          @onInput={{this.setTitle}}
+        />
+        <Args.String
+          @name='eyebrow'
+          @value={{this.eyebrow}}
+          @description='Small mono line above the title.'
+          @onInput={{this.setEyebrow}}
+        />
+        <Args.String
+          @name='lead'
+          @value={{this.lead}}
+          @description='One paragraph under the title.'
+          @onInput={{this.setLead}}
+        />
+        <Args.String
+          @name='mediaSide'
+          @value={{this.mediaSide}}
+          @defaultValue='start'
+          @options={{this.sideOptions}}
+          @description='Which side the panel sits on VISUALLY at wide widths. Source order stays content-first.'
+          @onInput={{this.setMediaSide}}
+        />
+        <Args.Object
+          @name='asset'
+          @description='The media panel asset, routed by MediaViewer. A video gets the kit player — transport, captions, keyboard, and no autoplay, which is what the source autoplaying GIF got wrong.'
+        />
+        <Args.String
+          @name='ratio'
+          @description='Hold the panel at a fixed aspect ratio.'
+        />
+        <Args.Yield
+          @name='media'
+          @description='Replaces the media panel. This is where a BrowserFrame will drop in once the kit has one.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-swm-gap'
+          @type='dimension'
+          @description='Gap between the panel and the steps at wide widths.'
+        />
+        <Css.Basic
+          @name='pretui-swm-media-fr'
+          @type='dimension'
+          @description='Track size for the media column.'
+        />
+        <Css.Basic
+          @name='pretui-swm-sticky-top'
+          @type='dimension'
+          @description='Sticky offset for the panel while the steps scroll past. Sticky is cancelled once the grid collapses, so a single column never pins the picture over the steps.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+  </template>
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// CtaBand
+// ═════════════════════════════════════════════════════════════════════════
+
+export const DEMOS_STEPS_WITH_MEDIA: Record<string, unknown> = {
+  StepsWithMedia: StepsWithMediaUsage,
+};

package/bundled-realms/pretui/components/streaming-text.gts

@@ -0,0 +1,77 @@
+// Pretui — StreamingText: text that reveals word by word without timers.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+
+export interface StreamingTextSignature {
+  Args: {
+    text: string;
+    // words per second for the CSS stagger (Law 7: seconds-based, unitless rates)
+    rate?: number;
+    startDelay?: number;
+    cursor?: boolean;
+  };
+  Element: HTMLSpanElement;
+}
+
+// Timer-free stream: each word carries animation-delay = start + i/rate.
+// Reduced motion / prerender shows the end state; sr-only mirror has full text.
+export class StreamingText extends Component<StreamingTextSignature> {
+  get words(): { word: string; style: ReturnType<typeof htmlSafe> }[] {
+    let rate = this.args.rate ?? 18;
+    let start = this.args.startDelay ?? 0;
+    return this.args.text.split(' ').map((word, i) => ({
+      word,
+      style: htmlSafe(`animation-delay: ${(start + i / rate).toFixed(3)}s`),
+    }));
+  }
+  <template>
+    <span class='pretui-stream' data-test-pretui-streaming-text ...attributes>
+      <span aria-hidden='true'>
+        {{#each this.words as |w|}}<span class='pretui-stream-word' style={{w.style}}>{{w.word}} </span>{{/each}}
+      </span>
+      <span class='pretui-sr'>{{@text}}</span>
+      {{#if @cursor}}<span class='pretui-stream-cursor' aria-hidden='true'></span>{{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        @keyframes pretui-stream-in {
+          from {
+            opacity: 0;
+            filter: blur(4px);
+          }
+          to {
+            opacity: 1;
+            filter: blur(0);
+          }
+        }
+        .pretui-stream-word {
+          display: inline;
+          opacity: 0;
+          animation: pretui-stream-in 420ms cubic-bezier(0.22, 0.61, 0.25, 1) both;
+        }
+        .pretui-stream-cursor {
+          display: inline-block;
+          width: 2px;
+          height: 0.9em;
+          vertical-align: -0.1em;
+          border-radius: 1px;
+          background: currentColor;
+          margin-left: 1px;
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip: rect(0 0 0 0);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-stream-word {
+            animation: none;
+            opacity: 1;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/streaming-text.md

@@ -0,0 +1,55 @@
+## What it is
+
+Text that appears word by word, as if being typed or streamed from a model. Use it for agent output, a generated summary landing on a card, or any moment where the arrival of the text is part of the experience. If you want a character-by-character effect with a blinking caret, that is **Typewriter**; if you want letters to scramble into place, **TextScramble**; if the text is simply present, do not animate it at all — an entrance animation on static content is noise.
+
+## The contract
+
+```
+@text: string   (required)
+@rate? (default 18, words per second)
+@startDelay? (default 0, seconds)
+@cursor?
+Element: HTMLSpanElement
+```
+
+**`@rate` is words per second, and the units matter.** Law 7 of the kit: rates are unitless numbers over seconds, never milliseconds-per-item, because a rate composes (two components at rate 18 agree) where a per-item delay does not. `@startDelay` is likewise seconds, so a sequence of streaming blocks can be choreographed by adding rates.
+
+**There is no timer.** Each word carries `animation-delay: startDelay + i / rate` seconds, and the whole reveal is CSS. That is the realm law — the prerenderer blocks timers — and it has three consequences worth knowing: the animation is correct under prerender (it simply shows the end state), it cannot leak, and **the text is fully present in the DOM from the first frame**. Nothing is being appended; opacity is being animated.
+
+That last point is what makes the accessibility work (below), and it is also the limitation: **this animates text you already have.** It is not a streaming transport. If tokens arrive incrementally from a model, each new `@text` re-runs the whole stagger from word zero. Streaming _into_ it needs a different approach.
+
+The entrance is opacity plus a 4px blur clearing over 420ms — the blur is what makes it read as "resolving" rather than "fading in".
+
+## Prior art
+
+**motion-primitives `TextEffect`** and **cult-ui's typewriter** are the closest — both drive per-character or per-word reveals through Framer Motion's stagger, i.e. a JS animation controller. **react-bits** ships several variants (`SplitText`, `BlurText`) on the same engine. **Vercel's AI SDK** streams tokens into a plain element and animates nothing.
+
+Where Pretui is better: **no runtime.** The reference implementations all instantiate an animation controller per instance, which on a page with twenty streamed blocks is twenty controllers driving RAF loops. Here it is `n` CSS animations the compositor owns, and the component's entire JS is one `map` producing delay strings. It also works where the others cannot — under prerender, and with `prefers-reduced-motion` handled by a single CSS rule rather than a conditional in the controller.
+
+Where it is behind: **no per-character mode**, no exit animation, no scroll-triggered start (compose **InView**), and the streaming-transport limitation above. motion-primitives' `TextEffect` also supports staggering _out_, which has no analogue here.
+
+## Accessibility
+
+No pattern governs it. Relevant criteria: WCAG **2.2.2 Pause, Stop, Hide**, **1.3.1**, and the live-region rules.
+
+This is one of the better-handled animations in the kit, and the technique is worth copying:
+
+- **A visually-hidden mirror carries the full text.** The animated words are inside an `aria-hidden="true"` wrapper, and a second `<span class='pretui-sr'>` holds `@text` complete. So a screen reader reads the whole sentence immediately and never encounters partially-revealed content, while the visual layer staggers. That is exactly right, and it is what most streaming-text implementations get wrong — they animate the real text and screen readers narrate fragments.
+- **The cursor is `aria-hidden`.** Correct — it is decoration.
+- **`prefers-reduced-motion: reduce` sets `animation: none; opacity: 1`**, so the end state appears immediately. Not a slower animation, not a fade: no motion at all, which is the right treatment for a decorative entrance.
+
+Gaps:
+
+- **The text is duplicated in the DOM.** The mirror is a second copy of the string, so `Ctrl+F`, text selection and copy-paste can pick up both. `clip: rect(0 0 0 0)` is the legacy visually-hidden recipe and does not prevent selection — a user dragging across the block may copy the sentence twice. The modern `clip-path: inset(50%)` recipe plus `user-select: none` on the mirror would tighten it.
+- **Nothing announces that streaming has finished.** The full text is available from the start, so there is nothing to wait for — which is the right design, but it means a live region wrapping this component would announce everything instantly and then again on the next update.
+- **WCAG 2.2.2** governs motion lasting more than five seconds. At the default rate of 18 words/second a paragraph resolves in well under a second, but a long document at a slow `@rate` can exceed it, and there is no pause control. Keep rates high enough that the whole block resolves quickly.
+- **The blur filter is a compositing cost** on long text; a 2,000-word block is 2,000 animated elements. Use it for short passages.
+- **Word splitting is `text.split(' ')`**, so multiple spaces collapse into empty words and the visual spacing comes from a trailing space inside each span. Text with newlines or tabs will not break as authored.
+
+## Theming
+
+Almost nothing: `currentColor` for the cursor, and the surrounding type styles are inherited. The 420ms duration, the `cubic-bezier(0.22, 0.61, 0.25, 1)` easing, the 4px blur and the 2px × 0.9em cursor are all fixed.
+
+`@rate` and `@startDelay` are args rather than tokens, so a theme cannot set a house streaming speed — that is a per-call-site decision. If a theme wants slower, calmer motion across the kit it can reach `--pretui-dur-*` elsewhere but not here, which is an inconsistency worth noting.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/streaming-text.usage.gts

@@ -0,0 +1,15 @@
+// Pretui — StreamingText usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { StreamingText } from './streaming-text';
+
+const StreamingTextUsage: TemplateOnlyComponent = <template>
+    <FreestyleUsage @name='StreamingText' @description='Timer-free word reveal for agent output. The full sentence remains available to assistive technology and reduced-motion users.' @source='<StreamingText @text="Comparing supplier records…" @rate={{12}} />'>
+      <:example><StreamingText @text='Comparing supplier records against 148 approved tea lots.' @rate={{12}} @cursor={{true}} /></:example>
+      <:api as |Args|><Args.String @name='text' @value='Comparing supplier records against 148 approved tea lots.' /><Args.Number @name='rate' @value={{12}} /><Args.Number @name='startDelay' @defaultValue={{0}} /><Args.Bool @name='cursor' @value={{true}} /></:api>
+    </FreestyleUsage>
+  </template>;
+
+export const DEMOS_STREAMING_TEXT: Record<string, unknown> = {
+  StreamingText: StreamingTextUsage,
+};