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

package/bundled-realms/pretui/components/property-sheet.md

@@ -0,0 +1,48 @@
+## What it is
+
+A property inspector built from a list of typed specs: rows, controls and values, assembled for you.
+
+**PropertyRow** is one row; **ValueInput** is one control. This is the panel.
+
+## The contract
+
+```
+@specs (required)  — the rows, in order
+@values (required) — current values, keyed by spec.key
+@layout?   — default row layout; each spec may override
+@disabled?
+@onChange? — fires with the key and the new value
+@onReset?  — invoked by a row's reset control
+
+<:custom> — receives [kind, value, spec, disabled] for kinds the sheet does not own
+```
+
+**A row shows a reset control only when the spec is `modified` *and* `@onReset` is supplied.** Both conditions, because a reset that cannot reset is worse than no reset, and a dot on an unmodified row is noise.
+
+**Values are keyed rather than positional**, so reordering `@specs` cannot silently reassign values.
+
+**`<:custom>` is the escape hatch for kinds ValueInput does not own** — colour above all — and it receives the kind alongside the value, so one block can handle several.
+
+## Prior art
+
+figui3's property sheets and the inspector panels in design tools.
+
+Where Pretui is better: the sheet is data-driven from typed specs rather than hand-assembled, so a panel of thirty properties is a list rather than thirty blocks of markup — and every row gets the label association, hint wiring and mixed-state handling right because **PropertyRow** does it once.
+
+Where it is thinner: no grouping or sections within a sheet, no collapsible categories, no search across properties, and no per-row validation.
+
+## Accessibility
+
+- **Every row's accessibility comes from PropertyRow**, so label association and hint description are correct by construction rather than per call site.
+- **`@disabled` applies to the sheet**, and rows mark themselves accordingly.
+- **Key-based values mean a row's label and its control always agree**, which is the failure mode of positional assembly.
+- **`<:custom>` inherits the row's yielded ids**, so a caller-supplied control is wired the same way a built-in one is — and a caller who ignores them breaks the association silently.
+- **A long sheet is a long list of form controls.** Grouping is the caller's to provide, and without it a thirty-property panel is thirty tab stops.
+
+## Theming
+
+Everything comes from **PropertyRow** and **ValueInput**; the sheet adds only stacking.
+
+That is the right shape: a property panel's appearance is its rows' appearance, and a sheet with its own surface would fight whichever inspector chrome it was placed in.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/property-sheet.usage.gts

@@ -0,0 +1,132 @@
+// Pretui — PropertySheet usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Panel } from './panel';
+import { PanelSection } from './panel-section';
+import { PropertySheet } from './property-sheet';
+import type { ValueOf, ValueSpec } from './value-input';
+import { BLEND_OPTIONS } from '../demo-design-value';
+
+const SHEET_SPECS: ValueSpec[] = [
+  { key: 'name', kind: 'text', label: 'Name', placeholder: 'Untitled' },
+  { key: 'visible', kind: 'toggle', label: 'Visible' },
+  {
+    key: 'opacity',
+    kind: 'number',
+    label: 'Opacity',
+    min: 0,
+    max: 100,
+    unit: '%',
+    precision: 0,
+  },
+  {
+    key: 'blend',
+    kind: 'select',
+    label: 'Blend',
+    options: BLEND_OPTIONS,
+  },
+  {
+    key: 'radius',
+    kind: 'number',
+    label: 'Radius',
+    min: 0,
+    max: 200,
+    unit: 'px',
+    precision: 0,
+    modified: true,
+  },
+  { key: 'rotate', kind: 'angle', label: 'Rotate' },
+  { key: 'shadow', kind: 'number', label: 'Shadow', unit: 'px', mixed: true },
+  {
+    key: 'origin',
+    kind: 'origin',
+    label: 'Origin',
+    layout: 'stack',
+  },
+];
+
+class PropertySheetUsage extends Component {
+  @tracked values: Record<string, ValueOf> = {
+    name: 'Hero card',
+    visible: true,
+    opacity: 100,
+    blend: 'normal',
+    radius: 24,
+    rotate: 0,
+    shadow: null,
+    origin: { x: 50, y: 50 },
+  };
+
+  change = (key: string, value: ValueOf) => {
+    this.values = { ...this.values, [key]: value };
+  };
+  reset = (key: string) => {
+    this.values = { ...this.values, [key]: key === 'radius' ? 8 : null };
+  };
+  specs = SHEET_SPECS;
+
+  <template>
+    <FreestyleUsage
+      @name='PropertySheet'
+      @description='A property panel rendered from data. The point is not brevity — it is that a panel defined as ValueSpec[] can come from a card schema, a plugin manifest, or a diffing multi-selection, and still get every affordance the hand-written rows have: labels wired to controls, hints wired to aria-describedby, mixed state as text, a reset where a value differs from its default, and the container-query fold.'
+      @source='<PropertySheet @specs={{this.specs}} @values={{this.values}} @onChange={{this.change}} />'
+    >
+      <:example>
+        <div class='pretui-sheet-demo'>
+          <Panel
+            @title='Properties'
+            @eyebrow='Hero card'
+            @variant='inspector'
+            @scroll={{true}}
+          >
+            <PanelSection @title='Layer' @summary='8'>
+              <PropertySheet
+                @specs={{this.specs}}
+                @values={{this.values}}
+                @onChange={{this.change}}
+                @onReset={{this.reset}}
+              />
+            </PanelSection>
+          </Panel>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Array
+          @name='specs'
+          @description='The rows, in order. Each carries its key, kind, label, hint, per-kind knobs and its mixed / modified state.'
+        />
+        <Args.Object
+          @name='values'
+          @description='Current values keyed by spec.key.'
+        />
+        <Args.String
+          @name='layout'
+          @description="Default row layout ('row' | 'stack' | 'split'); each spec may override."
+        />
+        <Args.Action
+          @name='onChange'
+          @description='Receives (key, value).'
+        />
+        <Args.Action
+          @name='onReset'
+          @description='Receives the key. A row only shows a reset control when its spec is modified AND this is supplied.'
+        />
+        <Args.Yield
+          @description='The custom block receives (kind, value, spec) for kinds ValueInput does not own.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-sheet-demo {
+        max-width: 300px;
+        height: 380px;
+        display: grid;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_PROPERTY_SHEET: Record<string, unknown> = {
+  PropertySheet: PropertySheetUsage,
+};

package/bundled-realms/pretui/components/prose.gts

@@ -0,0 +1,31 @@
+// Pretui — Prose: long-form text in the kit reading voice.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+export interface ProseSignature {
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+// The typographic reading surface — styles inline code per Law 3's quieter cousin.
+export const Prose: TemplateOnlyComponent<ProseSignature> = <template>
+  <div class='pretui-prose' data-test-pretui-prose ...attributes>{{yield}}</div>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-prose {
+        max-width: 62ch;
+        line-height: calc(var(--leading-body, 24px) / var(--text-body, 15px));
+      }
+      .pretui-prose :deep(p) {
+        margin: 0 0 var(--space-4, 11px);
+      }
+      .pretui-prose :deep(code) {
+        font-family: var(--font-mono);
+        font-size: 0.92em;
+        background: var(--inset, var(--boxel-100));
+        padding: 1px 5px;
+        border-radius: 5px;
+        box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+      }
+    }
+  </style>
+</template>;

package/bundled-realms/pretui/components/prose.md

@@ -0,0 +1,57 @@
+## What it is
+
+The typographic reading surface: a measure-limited container that styles the prose you put inside it. Use it to wrap authored body copy — a card's description, a markdown render, a README, an article body. It does not parse anything; it is CSS with a boundary. If the content is a single short paragraph inside a form, it does not need this. If it is a code sample, put a `<pre>` inside it. If it is a machine value inline, use **Token**, which is the louder cousin of what this styles `<code>` as.
+
+## The contract
+
+```
+<:default>
+Element: HTMLDivElement
+```
+
+No args. Two things happen inside it, and they are both worth stating because they are what you are actually buying.
+
+**`max-width: 62ch`.** The measure — the number of characters per line — is the single largest determinant of whether body copy is comfortable to read, and 62ch sits inside the 45–75 range typography research consistently lands on. Because it is `ch`, it tracks the font actually in use rather than assuming a pixel width. A card that renders prose full-bleed across a 1600px pane is unreadable, and this is the one line that prevents it.
+
+**`line-height: calc(var(--leading-body) / var(--text-body))`.** The leading is expressed as a _ratio derived from two absolute tokens_, so a theme sets a body size and a leading in pixels — the way a type scale is actually designed — and the ratio falls out. Setting `line-height` as a bare number would decouple them and let a theme's leading drift when it retunes the size.
+
+Paragraph margins (`0 0 var(--space-4)`) and inline `<code>` styling reach the yielded content through `:deep()`, which is the narrow, legitimate use of the escape hatch: the component must style markup it did not render.
+
+## Prior art
+
+**`@tailwindcss/typography`** (`prose`) is the reference and is enormously larger — it styles headings, lists, blockquotes, tables, figures, `<hr>`, links, and ships size and colour modifiers. **shadcn** has no prose component; its docs use the Tailwind plugin. **Web Awesome**, **Radix** and **React Spectrum** all ship nothing here — Spectrum's `Content`/`Text` are layout slots, not typographic surfaces.
+
+Pretui's version is **deliberately two rules**, and the honest framing is that this is a floor, not a competitor to `prose`. What it gets right that the minimal hand-rolled version does not: the measure is enforced (most in-house prose styles forget it), and the leading is derived from the type scale rather than guessed.
+
+What is missing versus `prose`, and it is a lot: **no heading styles, no list styles, no blockquote, no link treatment, no table styling, no `<pre>` block**. Content with an `<h3>` or a `<ul>` inside a Prose gets browser defaults, which will not match the kit. For a markdown render — the obvious use case — that is a real gap, and the practical consequence is that most markdown in this kit still looks like a browser default document below the paragraph level.
+
+The `<code>` treatment is the one element it does style, and it is coordinated: quieter than **Token** (a plain `--inset` fill, no hue) so inline code recedes into prose while a Token stands out. That distinction is deliberate and is the kit's Law 3 in two registers.
+
+## Accessibility
+
+No pattern governs it. The relevant criteria are WCAG **1.4.8 Visual Presentation** (AAA), **1.4.12 Text Spacing** (AA) and **1.4.10 Reflow** (AA).
+
+What is right, and it is genuinely more than most kits:
+
+- **`max-width: 62ch` directly serves WCAG 1.4.8**, which asks for no more than 80 characters per line. Comfortably inside it.
+- **Leading derived from the type scale** rather than hardcoded means a theme that increases body size gets proportional leading. WCAG **1.4.12** requires content to survive a user stylesheet setting line-height to 1.5× — since the leading here is a ratio on a `div` and paragraph margins are in `--space-4`, user overrides apply cleanly rather than fighting a fixed pixel `line-height`.
+- **Reflow**: `max-width` with no `min-width` means the surface shrinks correctly at 320px.
+
+Gaps:
+
+- **Unstyled headings are a structural risk, not just a visual one.** Because `Prose` styles nothing above the paragraph, authors are tempted to fake headings with bold paragraphs — which produces content with no heading structure at all (**WCAG 1.3.1**, and a navigation failure for screen-reader users). Styling `<h2>`–`<h4>` would remove the temptation.
+- **Links are unstyled**, so they inherit the browser's blue-and-underlined default, which will not match the theme and may not meet **1.4.3** against a themed background. It also means link/non-link distinction is whatever the UA decides.
+- **Lists are unstyled**, so nested lists inherit default indentation that will not match the kit's spacing scale.
+- **No `text-wrap: pretty` or `balance`**, so headings and short paragraphs get orphans. Minor, and a one-line improvement.
+- **The `<code>` fill is `--inset` with a hairline**, at `0.92em`. That is small text at low contrast against a low-contrast fill; check per theme.
+- Nothing is focusable; anything interactive inside is the caller's.
+
+## Theming
+
+`--leading-body` and `--text-body` (which together produce the line-height ratio), `--space-4` (paragraph spacing), and for inline code: `--font-mono`, `--inset`, `--border`, `--pretui-shadow-hairline`.
+
+The `62ch` measure is fixed and is the one thing a theme most often wants to change — a display-face theme with a wide font may want 58ch, a condensed one 68ch. There is no token for it, so changing the measure means changing the component.
+
+Because everything else inside is unstyled, **a theme's control over prose is limited to the type scale tokens**; heading, list and link appearance inside a Prose are the browser's, whatever the theme says.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/prose.usage.gts

@@ -0,0 +1,15 @@
+// Pretui — Prose usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { Prose } from './prose';
+
+const ProseUsage: TemplateOnlyComponent = <template>
+    <FreestyleUsage @name='Prose' @description='A restrained reading measure for authored text. Paragraph rhythm and inline machine values are styled without becoming a document renderer.' @source='<Prose><p>…</p></Prose>'>
+      <:example><Prose><p>The first-flush Gyokuro arrived from Shizuoka under lot <code>B-103</code>. Its reserve is unchanged after sensory review.</p><p>Use <code>records@2.4.0</code> when importing the supplier manifest.</p></Prose></:example>
+      <:api as |Args|><Args.Yield @name='default' @description='Semantic prose content.' /></:api>
+    </FreestyleUsage>
+  </template>;
+
+export const DEMOS_PROSE: Record<string, unknown> = {
+  Prose: ProseUsage,
+};

package/bundled-realms/pretui/components/pulsing-border.gts

@@ -0,0 +1,297 @@
+// Pretui — PulsingBorder: a border that pulses or trails to draw attention to a surface.
+import Component from '@glimmer/component';
+import { Chip } from './chip';
+import { statusHue } from '../internal/ink';
+import { clampNum, cssValue, styleFrom } from '../internal/texture';
+
+// ── PulsingBorder ────────────────────────────────────────────────────────
+
+/** `pulse` = breathing halo; `trail` = a light travelling the ring. */
+export type PulsingBorderVariant = 'pulse' | 'trail';
+
+/** Where the text affordance sits on the boundary. */
+export type PulsingBorderMarker =
+  | 'top-start'
+  | 'top-end'
+  | 'bottom-start'
+  | 'bottom-end';
+
+export interface PulsingBorderSignature {
+  Args: {
+    /** The text affordance — what the pulse MEANS ("Live", "Streaming", "Recording"). Law 6: a pulsing border alone is invisible to a screen reader and unindexable, so this always renders (visibly, or sr-only when `@marker={{false}}`). */
+    label?: string;
+    /** Is it actually live? False rests the ring on the neutral border color and stops all motion — the label should change with it. */
+    active?: boolean;
+    /** `pulse` (breathing halo) or `trail` (a light travelling the ring). */
+    variant?: PulsingBorderVariant;
+    /** Ring hue. Defaults to `statusHue(label)` — Law 2: the same word gets the same hue on every card. */
+    hue?: string;
+    /** Motion rate multiplier (1 = natural). */
+    speed?: number;
+    /** Ring thickness in px. Default 1.5. */
+    thickness?: number;
+    /** Render the affordance visibly on the boundary. False keeps it sr-only — for when the surrounding UI already carries the words. It never disappears entirely. */
+    marker?: boolean;
+    /** Corner of the boundary the affordance sits on. */
+    markerPlacement?: PulsingBorderMarker;
+  };
+  Blocks: {
+    /** The bounded content. */
+    default: [];
+    /** Replaces the affordance text with your own markup (Law 7: anything visual a caller might replace is a slot). */
+    label: [];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * The "this is live" boundary treatment — and the canonical Law 6 borderline
+ * case. A pulsing border on its own is information carried entirely by
+ * texture: invisible to a screen reader, unindexable, and gone from a still
+ * frame. So the affordance is not optional here. The component renders a
+ * `role='status'` marker (an ink `Chip`, reused rather than re-drawn) on the
+ * boundary itself; `@marker={{false}}` demotes it to sr-only text but never
+ * removes it.
+ *
+ * Ported in behavior from react-bits' ElectricBorder / StarBorder and
+ * motion-primitives' BorderTrail. Dropped: their canvas/WebGL electric
+ * distortion (Law 9), and their assumption that a border can say "live"
+ * unaccompanied. Improved: the ring is an inset `box-shadow` rather than a
+ * `border`, so turning it on never reflows the content (Law 1 — depth is one
+ * property); the halo animates `transform`/`opacity` only; and the resting
+ * state is a visible hairline + soft glow, so it survives the screenshot
+ * test (Law 8) and reduced motion identically.
+ */
+export class PulsingBorder extends Component<PulsingBorderSignature> {
+  get label(): string {
+    return this.args.label ?? 'Live';
+  }
+  get active(): boolean {
+    return this.args.active ?? true;
+  }
+  get variant(): PulsingBorderVariant {
+    return this.args.variant === 'trail' ? 'trail' : 'pulse';
+  }
+  get isTrail(): boolean {
+    return this.variant === 'trail';
+  }
+  get showMarker(): boolean {
+    return this.args.marker ?? true;
+  }
+  get markerPlacement(): PulsingBorderMarker {
+    return this.args.markerPlacement ?? 'top-start';
+  }
+  // Law 2: one hue in, a complete treatment out — and when the caller does
+  // not name one, derive it from the value so "Live" is the same hue on
+  // every card by every author.
+  get hue(): string {
+    return cssValue(this.args.hue) ?? statusHue(this.label);
+  }
+  get chipHue(): string {
+    return this.active ? this.hue : 'var(--muted-foreground)';
+  }
+  get style() {
+    let parts: string[] = [`--pretui-pb-hue: ${this.hue}`];
+    let speed = clampNum(this.args.speed, 0.05, 6);
+    if (speed !== undefined) parts.push(`--pretui-pb-speed: ${speed}`);
+    let thickness = clampNum(this.args.thickness, 0.5, 8);
+    if (thickness !== undefined) {
+      parts.push(`--pretui-pb-thickness: ${thickness}px`);
+    }
+    return styleFrom(parts);
+  }
+  <template>
+    <div
+      class='pretui-pb'
+      data-variant={{this.variant}}
+      data-active={{if this.active 'true' 'false'}}
+      data-marker={{this.markerPlacement}}
+      style={{this.style}}
+      data-test-pretui-pulsing-border
+      ...attributes
+    >
+      <span class='pretui-pb-ring' aria-hidden='true'></span>
+      {{#if this.isTrail}}
+        <span class='pretui-pb-trail' aria-hidden='true'></span>
+      {{else}}
+        <span class='pretui-pb-halo' aria-hidden='true'></span>
+      {{/if}}
+
+      {{#if this.showMarker}}
+        <span
+          class='pretui-pb-marker'
+          role='status'
+          data-test-pretui-pulsing-border-marker
+        >
+          <Chip @hue={{this.chipHue}}>
+            {{#if (has-block 'label')}}{{yield to='label'}}{{else}}{{this.label}}{{/if}}
+          </Chip>
+        </span>
+      {{else}}
+        <span
+          class='pretui-pb-sr'
+          role='status'
+          data-test-pretui-pulsing-border-marker
+        >{{#if (has-block 'label')}}{{yield to='label'}}{{else}}{{this.label}}{{/if}}</span>
+      {{/if}}
+
+      <div class='pretui-pb-body'>{{yield}}</div>
+    </div>
+    <style scoped>
+      @property --pretui-pb-angle {
+        syntax: '<angle>';
+        inherits: false;
+        initial-value: 0deg;
+      }
+      @layer PretComponent {
+        .pretui-pb {
+          position: relative;
+          border-radius: var(--pretui-pb-radius, var(--radius-surface, 10px));
+          isolation: isolate;
+        }
+        /* Law 1: the boundary is a shadow, not a border — switching it on can
+           never reflow the content it wraps. */
+        .pretui-pb-ring {
+          position: absolute;
+          inset: 0;
+          border-radius: inherit;
+          pointer-events: none;
+          z-index: 2;
+          box-shadow: inset 0 0 0 var(--pretui-pb-thickness, 1.5px)
+            color-mix(
+              in oklch,
+              var(--pretui-pb-hue, var(--primary)) 72%,
+              transparent
+            );
+        }
+        .pretui-pb[data-active='false'] .pretui-pb-ring {
+          box-shadow: inset 0 0 0 var(--pretui-pb-thickness, 1.5px)
+            var(--border);
+        }
+        /* resting state = a soft static glow (screenshot test); the keyframes
+           only add the breathing on top of it */
+        .pretui-pb-halo {
+          position: absolute;
+          inset: 0;
+          border-radius: inherit;
+          pointer-events: none;
+          z-index: 0;
+          opacity: 0.42;
+          box-shadow: 0 0 0 3px
+            color-mix(
+              in oklch,
+              var(--pretui-pb-hue, var(--primary)) 30%,
+              transparent
+            );
+        }
+        @keyframes pretui-pb-breathe {
+          from {
+            opacity: 0.42;
+            transform: scale(1);
+          }
+          to {
+            opacity: 0;
+            transform: scale(1.028);
+          }
+        }
+        .pretui-pb[data-active='true'] .pretui-pb-halo {
+          animation: pretui-pb-breathe calc(2.6s / var(--pretui-pb-speed, 1))
+            cubic-bezier(0.23, 1, 0.32, 1) infinite;
+        }
+        .pretui-pb[data-active='false'] .pretui-pb-halo {
+          opacity: 0;
+        }
+
+        /* trail: a conic sweep clipped to the ring band by a two-layer mask.
+           The angle is a registered custom property so the sweep is one
+           declaration; if @property is unavailable the fallback angle still
+           resolves and the ring rests as a static gradient boundary. */
+        .pretui-pb-trail {
+          position: absolute;
+          inset: 0;
+          border-radius: inherit;
+          pointer-events: none;
+          z-index: 1;
+          padding: calc(var(--pretui-pb-thickness, 1.5px) + 1px);
+          background: conic-gradient(
+            from var(--pretui-pb-angle, 0deg),
+            transparent 0turn 0.55turn,
+            color-mix(
+                in oklch,
+                var(--pretui-pb-hue, var(--primary)) 45%,
+                transparent
+              )
+              0.82turn,
+            var(--pretui-pb-hue, var(--primary)) 0.94turn,
+            transparent 1turn
+          );
+          mask-image: linear-gradient(rgb(0 0 0 / 1) 0 0),
+            linear-gradient(rgb(0 0 0 / 1) 0 0);
+          mask-clip: content-box, border-box;
+          mask-composite: exclude;
+        }
+        @keyframes pretui-pb-sweep {
+          to {
+            --pretui-pb-angle: 360deg;
+          }
+        }
+        .pretui-pb[data-active='true'] .pretui-pb-trail {
+          animation: pretui-pb-sweep calc(4.5s / var(--pretui-pb-speed, 1))
+            linear infinite;
+        }
+        .pretui-pb[data-active='false'] .pretui-pb-trail {
+          opacity: 0.3;
+        }
+
+        .pretui-pb-marker {
+          position: absolute;
+          z-index: 3;
+          display: inline-flex;
+          line-height: 0;
+        }
+        .pretui-pb[data-marker='top-start'] .pretui-pb-marker {
+          top: 0;
+          left: var(--space-4, 11px);
+          transform: translateY(-50%);
+        }
+        .pretui-pb[data-marker='top-end'] .pretui-pb-marker {
+          top: 0;
+          right: var(--space-4, 11px);
+          transform: translateY(-50%);
+        }
+        .pretui-pb[data-marker='bottom-start'] .pretui-pb-marker {
+          bottom: 0;
+          left: var(--space-4, 11px);
+          transform: translateY(50%);
+        }
+        .pretui-pb[data-marker='bottom-end'] .pretui-pb-marker {
+          bottom: 0;
+          right: var(--space-4, 11px);
+          transform: translateY(50%);
+        }
+        .pretui-pb-body {
+          position: relative;
+          z-index: 1;
+          border-radius: inherit;
+        }
+        .pretui-pb-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          margin: -1px;
+          padding: 0;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+          border: 0;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-pb-halo,
+          .pretui-pb-trail {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/pulsing-border.md

@@ -0,0 +1,65 @@
+## What it is
+
+A ring around a surface that says "this is live": a pulsing hairline plus a soft halo, with a **required** text marker on the boundary. Use it on something actively receiving updates — a streaming panel, a running job, a connected session. If the state is a value rather than a liveness, use **Chip** or **StatusChip**. If it is progress toward a known end, **ProgressBar**. If it is a decorative accent, do not use this at all — the marker is not optional, and the component will not let you have the glow without it.
+
+## The contract
+
+```
+@label? ('Live'), @active? (true)
+@variant? 'pulse' | 'trail'   (default 'pulse')
+@marker? (default true), @markerPlacement? (default 'top-start')
+@hue?
+```
+
+**`@marker={{false}}` demotes the marker to visually-hidden text — it never removes it.** That is the component's central rule and the source states the reasoning: **a pulsing border on its own is information carried entirely by texture** — invisible to a screen reader, unindexable, and gone from a still frame. So the affordance is not optional. The marker is an ink **Chip**, reused rather than re-drawn, carrying `role="status"`.
+
+**The ring is an inset `box-shadow`, not a `border`**, so turning it on never reflows the content (Law 1 — depth is one property). Every hand-rolled version of this adds a border and shifts everything inside by a pixel.
+
+**The halo animates `transform` and `opacity` only**, so it stays on the compositor.
+
+**The resting state is a visible hairline plus a soft glow**, which means the component survives the screenshot test (Law 8) and reduced motion identically — a still frame of a live panel still reads as live.
+
+`@hue` overrides the Law-2 derivation.
+
+## Prior art
+
+Ported in behaviour from **react-bits' `ElectricBorder` / `StarBorder`** and **motion-primitives' `BorderTrail`**.
+
+**Dropped:** their canvas/WebGL electric distortion (Law 9 — no vendored engines), and — the substantive one — **their assumption that a border can say "live" unaccompanied.** All three upstreams are decorative components that people then use to convey state, and none of them carries text.
+
+**Improved**, and each is concrete:
+
+- **Inset `box-shadow` instead of a `border`**, so activation causes no reflow.
+- **`transform`/`opacity`-only animation**, so the halo does not trigger layout or paint.
+- **A resting state that is visible without motion** — the upstreams are invisible when static, so a reduced-motion user or a screenshot sees nothing at all.
+- **The mandatory marker** (above).
+
+Where it is thinner: no colour cycling, no gradient sweep beyond the `trail` variant, and no multi-hue effects. Those all belong to the decorative category this component deliberately left.
+
+## Accessibility
+
+No APG pattern; the criteria are WCAG **1.4.1 Use of Colour**, **4.1.3 Status Messages**, **2.2.2 Pause, Stop, Hide** and **2.3.3**.
+
+This is the best-behaved decorative component in the kit, and the reason is the marker:
+
+- **`role="status"` on the marker** means the liveness is announced, and it is announced as text rather than implied by a glow.
+- **`@marker={{false}}` keeps the text, visually hidden** — so a caller who wants a clean surface still ships the information. Making the accessible affordance un-removable is a design pattern worth copying elsewhere in the kit (**Meter**'s required `@label` is the other example).
+- **Colour is never the only channel**: hue plus a hairline plus a word.
+- **The resting state is visible without motion**, so reduced-motion users are not left with an unmarked surface.
+
+Gaps:
+
+- **`role="status"` is a live region created with its content already in it.** The same problem **Alert**, **Toast**, **Spinner** and **LoadingState** have: a region that mounts complete is frequently not announced. If the point is to announce _becoming_ live, the marker should exist before `@active` flips — render the component with `@active={{false}}` rather than mounting it on activation.
+- **`@label` defaults to `'Live'`**, so two live panels announce identically and neither says what is live.
+- **`@active={{false}}` presumably stops the pulse**; whether the marker's text changes to say so is worth checking — a `role="status"` still reading "Live" on an inactive surface is worse than no marker.
+- **The pulse runs indefinitely.** **WCAG 2.2.2** governs motion that starts automatically, lasts more than five seconds and runs alongside other content; a live panel qualifies, and there is no pause control. The reduced-motion path covers users who set the preference and no one else.
+- Verify a `prefers-reduced-motion` rule exists — the source implies the resting state doubles as the reduced-motion state, which is the right design, but it must actually be wired.
+- No `forced-colors` treatment; a glow drawn with `box-shadow` is commonly dropped in High Contrast mode, leaving only the marker — which is, at least, the important half.
+
+## Theming
+
+The Law-2 hue derivation (one hue in, ring, halo and marker tint all derived), `--card` and `--border` for the resting hairline, plus the **Chip** tokens the marker reuses (`--pretui-chip-mix`, `--pretui-ink-mix`) and the animation's duration and easing.
+
+Because the ring is a `box-shadow` and the halo is a transform, a theme retunes intensity by changing the hue and the mix ratios rather than by changing geometry. A theme must keep the _resting_ hairline visible — it is what carries the state in a screenshot and under reduced motion, and a theme that tunes only the animated peak will produce a component that says nothing when still.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.