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

package/bundled-realms/pretui/internal/structure-morph.gts

@@ -0,0 +1,140 @@
+// Pretui — structure/morph: surfaces whose motion IS the state change.
+//
+//   AnimatedImage    animated GIF/WEBP with a real pause control
+//   DynamicIsland    a status capsule that morphs between three views
+//   MorphingDialog   a card that grows into its own modal dialog
+//   MorphingPopover  a trigger that grows into its own anchored panel
+//
+// ── Law 5 is the entrance exam for this whole file ───────────────────────
+//
+// "Motion is allowed where it encodes a state transition the reader would
+// otherwise have to infer; forbidden where it merely decorates." Every
+// animation here is the visible form of a state change and nothing here
+// animates at rest:
+//
+//   AnimatedImage    the motion IS the content; the component's own job is
+//                    to make it STOPPABLE (WCAG 2.2.2) and to start stopped
+//                    when the reader asked for less motion.
+//   DynamicIsland    idle → compact → expanded. The capsule growing is what
+//                    tells you the same object gained detail rather than a
+//                    second object appearing.
+//   Morphing*        this surface came FROM that trigger. Without the morph
+//                    the reader has to work out which of six cards opened.
+//
+// And every one of them lands on the END STATE under
+// `prefers-reduced-motion: reduce` — the dialog is simply open, the island
+// is simply expanded, the image is simply paused. Never a frozen midpoint.
+//
+// ── Reuse, not a second Dialog ───────────────────────────────────────────
+//
+// `MorphingDialog` wraps `Dialog` from overlay.gts and `MorphingPopover`
+// wraps `Popup`. The focus trap, Escape, the top layer, `::backdrop` and
+// focus RETURN all come from the native `<dialog>` element that `Dialog`
+// already drives correctly; the anchored placement, flip and shift come from
+// `anchorTo`. Nothing about either of those was re-implemented — the only
+// thing added is the morph, and it is added through ONE shared primitive
+// (`morphFrom`) rather than twice.
+//
+// Pretui — shared motion helpers for the morphing components (morphFrom and friends).
+import { cancel, scheduleOnce } from '@ember/runloop';
+import { modifier } from 'ember-modifier';
+
+// ── Shared ───────────────────────────────────────────────────────────────
+
+export function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+function clamp(value: number, low: number, high: number): number {
+  return Math.min(high, Math.max(low, value));
+}
+
+/**
+ * THE morph primitive, and the reusable artifact of this file.
+ *
+ * Given the rectangle a surface came FROM, it animates the surface from that
+ * rectangle's position and size to its own. This is a FLIP: the surface is
+ * already laid out at its final geometry when the animation starts, so the
+ * end state is the truth and the start state is the inversion of it. Nothing
+ * is measured twice and no layout is faked.
+ *
+ * Three deliberate mechanism choices, each of which is the reason the
+ * alternative was rejected:
+ *
+ *  * **`element.animate()` (WAAPI), not a CSS transition.** The exact
+ *    translate/scale pair is only knowable at open time, and it must
+ *    OUTRANK the transition the wrapped component already declares on the
+ *    same element. A web animation wins that by cascade rank, so no
+ *    specificity game — no doubled class, no `!important` — is needed to
+ *    take over an element another component styles.
+ *  * **`@starting-style` was not enough.** It cannot read a geometry that
+ *    is only known once both boxes exist, and the wrapped `Dialog` already
+ *    owns a `@starting-style` rule on the same element.
+ *  * **`scheduleOnce('afterRender')`, not `requestAnimationFrame`.** The
+ *    measurement cannot happen in the modifier body: a modal `<dialog>` is
+ *    `display: none` until the component's own modifier calls `showModal()`,
+ *    and modifier ordering between a wrapper and the component it wraps is
+ *    not something to bet an animation on. The `afterRender` queue runs once
+ *    every modifier in the transaction has, so the element is always laid
+ *    out by then — and unlike a rAF it is INSIDE the runloop, so
+ *    `await settled()` waits for it and a test can never race it. The token
+ *    is cancelled in the destructor.
+ *
+ * Passing `undefined` (or running under reduced motion) does nothing at all,
+ * which is how the reduced-motion path lands on the end state: the surface
+ * is simply there.
+ */
+export const morphFrom = modifier(
+  (element: HTMLElement, [origin]: [DOMRect | undefined]) => {
+    if (!origin || prefersReducedMotion()) {
+      return;
+    }
+    let animation: Animation | undefined;
+    // Hoisted rather than inlined: `scheduleOnce` dedupes on the identity of
+    // (target, method), and an inline function expression is a fresh
+    // identity every call — which is why the lint rule rejects one.
+    let start = () => {
+      // Forces layout, which is what makes the measurement true even on the
+      // frame the dialog was promoted to the top layer.
+      let rect = element.getBoundingClientRect();
+      if (rect.width < 1 || rect.height < 1) {
+        return;
+      }
+      let sx = clamp(origin.width / rect.width, 0.04, 1);
+      let sy = clamp(origin.height / rect.height, 0.04, 1);
+      let dx = origin.left + origin.width / 2 - (rect.left + rect.width / 2);
+      let dy = origin.top + origin.height / 2 - (rect.top + rect.height / 2);
+      animation = element.animate(
+        [
+          {
+            transform:
+              'translate(' +
+              dx.toFixed(1) +
+              'px, ' +
+              dy.toFixed(1) +
+              'px) scale(' +
+              sx.toFixed(4) +
+              ', ' +
+              sy.toFixed(4) +
+              ')',
+            opacity: 0.2,
+          },
+          // The content is legible well before the box stops moving, which
+          // is what stops a non-uniform scale from reading as a squash.
+          { opacity: 1, offset: 0.4 },
+          { transform: 'translate(0px, 0px) scale(1, 1)', opacity: 1 },
+        ],
+        { duration: 300, easing: 'cubic-bezier(0.23, 1, 0.32, 1)' },
+      );
+    };
+    let scheduled = scheduleOnce('afterRender', element, start);
+    return () => {
+      cancel(scheduled);
+      animation?.cancel();
+    };
+  },
+);

package/bundled-realms/pretui/internal/structure-scenes.gts

@@ -0,0 +1,25 @@
+// Pretui — structure territory, scenes wave: four scene-setting layout
+// pieces TRANSCRIBED (not wrapped — no boxel-ui engine exists for these)
+// from their JS-motion originals into CSS-first Glimmer:
+//   Marquee       ← fancy SimpleMarquee (rAF motion-value engine → pure
+//                   CSS keyframe loop; TIMER LAW: no JS timers)
+//   Comparison    ← webawesome wa-comparison semantics (role=slider seam,
+//                   arrow/Home/End keys) + motion-primitives
+//                   ImageComparison layer-clip idea, drag via the
+//                   pointer-capture modifier pattern (freestyle Viewport)
+//   StackingCards ← fancy StackingCards (scroll-progress transforms →
+//                   pure position:sticky pinning + static nth-child scale)
+//   Dock          ← motion-primitives Dock (cursor-distance spring
+//                   magnification → :hover/:has sibling falloff)
+// Theming contract: no dark-mode branches; every color is
+// var(--token, lightFallback); prefers-reduced-motion honored wherever
+// anything moves. Per-component delta notes sit on each section.
+//
+// Pretui — shared helpers for the scene components.
+
+export function clamp01to100(v: number): number {
+  return Math.min(100, Math.max(0, v));
+}
+export function styleVar(name: string, value: string): string {
+  return `${name}: ${value}`;
+}

package/bundled-realms/pretui/internal/structure-scroll.gts

@@ -0,0 +1,72 @@
+// Pretui — structure/scroll: the viewport family.
+//
+// Three components, in dependency order:
+//
+//   Scroller       a scroll container that TELLS you it is clipped
+//   Carousel       a scroll-snap track with keyboard, dots and a status
+//                  line — composed ON Scroller, not beside it
+//   ZoomableFrame  a zoom-and-pan viewport around framed content
+//
+// `Scroller` is deliberately first and deliberately small: "content
+// continues past this edge" is a fact half the kit's collections need, and
+// before this it was re-solved (or skipped) per component. `Carousel`
+// consumes it rather than reimplementing edge detection: the primitive is
+// built before its consumers.
+//
+// ── The realm's timer law, and how the whole file obeys it ───────────────
+//
+// No `setTimeout`, no `setInterval`, no rAF loop, no `Date.now()`, no
+// `Math.random()`. Everything reactive here is either an EVENT LISTENER or
+// an OBSERVER, every one owned by an `ember-modifier` that removes or
+// disconnects it in the destructor:
+//
+//   scroll / pointer* / wheel / keydown   listeners  (removed on teardown)
+//   ResizeObserver                        overflow + geometry (disconnected)
+//   IntersectionObserver                  which slide is showing (disconnected)
+//
+// The one place a timer would be idiomatic — carousel auto-advance — is
+// therefore NOT SHIPPED, and that is a deliberate, stated decision rather
+// than an omission: a re-arming timer blocks `await settled()` and hangs the
+// test suite for every agent working in this realm. The accessibility
+// guidance ("must not auto-advance without consent, and `prefers-
+// reduced-motion` suppresses it entirely") is satisfied by construction, and
+// `@onIndexChange` is the seam a host outside the realm can drive.
+//
+// Pretui — shared helpers for Scroller, Carousel and ZoomableFrame: reduced motion, scroll behaviour, clamp.
+
+// ── Shared helpers ───────────────────────────────────────────────────────
+
+/** True when the reader has asked the platform for less motion. */
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+/** Reduced motion lands on the END STATE — an instant jump, never a frozen
+ * midpoint (Law 5). */
+export function scrollBehavior(): ScrollBehavior {
+  return prefersReducedMotion() ? 'auto' : 'smooth';
+}
+
+export function clamp(value: number, low: number, high: number): number {
+  return Math.min(high, Math.max(low, value));
+}
+
+/** The nearest ancestor that scrolls, or null for the viewport — what a
+ * pane-local observer or sticky element measures against. */
+export function scrollParent(el: HTMLElement): HTMLElement | null {
+  let node = el.parentElement;
+  while (node) {
+    let style = getComputedStyle(node);
+    if (SCROLLS.test(style.overflowY + ' ' + style.overflowX)) {
+      return node;
+    }
+    node = node.parentElement;
+  }
+  return null;
+}
+
+const SCROLLS = /(auto|scroll|overlay)/;

package/bundled-realms/pretui/internal/structure-shell-fixtures.gts

@@ -0,0 +1,25 @@
+// Pretui — fixtures shared by the structure-shell usage pages.
+import { PLACES, TEAS, seedFrom, take } from '../examples';
+
+export 
+const SHELL_SEED = seedFrom('pretui-shell-demo');
+
+export 
+interface NavRow {
+  id: string;
+  label: string;
+  badge?: string;
+}
+
+export 
+const LIBRARY: NavRow[] = take(SHELL_SEED, 0, 4, TEAS).map((tea, i) => ({
+  id: 'lib-' + i,
+  label: tea,
+  badge: String(4 + (seedFrom('nav#' + tea) % 40)),
+}));
+
+export 
+const ORIGINS: NavRow[] = take(SHELL_SEED, 1, 3, PLACES).map((place, i) => ({
+  id: 'org-' + i,
+  label: place,
+}));

package/bundled-realms/pretui/internal/surfaces-canvas-fixtures.gts

@@ -0,0 +1,5 @@
+// Pretui — fixtures shared by the surfaces-canvas usage pages.
+import type { CanvasNode } from './surfaces-canvas';
+
+export const NO_NODES: CanvasNode[] = [];
+export const SUMMARIES = ['sr-only', 'visible', 'off'];

package/bundled-realms/pretui/internal/surfaces-canvas.gts

@@ -0,0 +1,283 @@
+// Pretui — surfaces territory: the two components that only Boxel can
+// ship, because only Boxel has the `surfaces` packages sitting under the
+// wardrobe. Both are wraps: the engine stays the library's, only the cloth
+// changes.
+//
+//   NodeCanvas   ← @cardstack/boxel-canvas  (a Glimmer port of xyflow /
+//                  React Flow, vendored from emberflow). Infinite
+//                  pan/zoom node graph: nodes, edges, dot/line/cross
+//                  background, zoom controls, minimap.
+//   PageScaffold ← @cardstack/boxel-layout  (`Layout` + its four presets
+//                  bare / page / notebook / tools). Application frame with
+//                  named landmark regions. Upstream reference: wa-page.
+//
+// Both import the surfaces realm bundle copied into this realm at
+// ./surfaces/ (self-contained ESM — xyflow is inlined; only host-provided
+// modules are external). Relative in-realm imports, not cross-realm
+// common-libs URLs: local `boxel parse` can resolve mirror-local files but
+// not authed remote ones.
+//
+// ── The canvas stylesheet problem, and how this module solves it ────────
+// boxel-canvas is the one surfaces package that needs a companion
+// stylesheet (surfaces/canvas/styles/canvas.css). The npm package pulls it
+// in with a side-effect `import './styles/canvas.css'`, which is BANNED in
+// realm code: it passes parse, remote lint AND transpile, then fails at
+// indexing with `Unexpected token (28:0)` because the realm loader fetches
+// the CSS and parses it as JavaScript. A bare <link> to the realm-served
+// URL 401s (private realm, header auth). So the sheet ships as a string
+// module (surfaces-canvas-css.ts) and the `canvasStylesheet` modifier
+// below injects it into document.head, refcounted so N canvases share one
+// <style> and the last teardown removes it.
+//
+// That same modifier injects a SECOND sheet, PRETUI_CANVAS_SKIN, for the
+// handful of engine-owned elements that no custom property can reach
+// (focus rings the engine explicitly sets to `outline: none`, the
+// reduced-motion fallback the engine never wrote). Every selector in it is
+// anchored under `.pretui-node-canvas`, so it cannot leak past a
+// NodeCanvas. Everything else is retinted through the engine's own
+// `--xy-*` custom-property channel from `<style scoped>` — no :global(),
+// no :deep(), no !important.
+//
+// Pretui — the canvas stylesheet primitive and the data shapes NodeCard and NodeCanvas share.
+import { modifier } from 'ember-modifier';
+import { CANVAS_CSS } from '../surfaces-canvas-css';
+
+// ── canvasStylesheet — exported primitive ────────────────────────────────
+// Any sibling that mounts a boxel-canvas needs this; it is exported rather
+// than buried so the next canvas-shaped component reuses it instead of
+// re-deriving the injection dance. A `data-refs` attribute on the <style>
+// counts the mounted canvases, so the last teardown is the one that removes
+// it.
+
+const ENGINE_SHEET_ID = 'pretui-surfaces-canvas-css';
+const SKIN_SHEET_ID = 'pretui-surfaces-canvas-skin';
+
+// Engine-owned elements that custom properties cannot reach. Each rule is
+// anchored under .pretui-node-canvas so nothing escapes the component.
+// What upstream got wrong, itemised:
+//   1. `.boxel-canvas__node.selectable:focus-visible { outline: none }`
+//      and the same on `__edge` and `__selection` — a keyboard user
+//      tabbing through the graph sees nothing at all. Restored, using the
+//      Pretui --ring token.
+//   2. The controls buttons have no focus style either, and the container
+//      has square corners with the engine's fixed shadow.
+//   3. `animation: dashdraw .5s linear infinite` on animated edges has no
+//      `prefers-reduced-motion` fallback anywhere in canvas.css. Restored
+//      with the END state (dashoffset 0), never a frozen midpoint.
+//   4. Every engine panel is pinned to `bottom: 0`, so the Controls and
+//      the MiniMap sit UNDER the caption strip that `@summary='visible'`
+//      draws. The strip's height is a knob and the bottom panels lift by
+//      exactly that much.
+// The one `outline: none` below is a REPLACEMENT, not a removal: an SVG
+// edge cannot show an outline usefully, so the focused edge is redrawn in
+// the ring colour at a heavier stroke on the line after it.
+const PRETUI_CANVAS_SKIN = `
+.pretui-node-canvas .boxel-canvas__node:focus-visible,
+.pretui-node-canvas .boxel-canvas__node.selectable:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 3px;
+  border-radius: var(--pretui-node-radius, var(--radius-surface, 10px));
+}
+.pretui-node-canvas .boxel-canvas__edge:focus-visible {
+  outline: none;
+}
+.pretui-node-canvas .boxel-canvas__edge:focus-visible .boxel-canvas__edge-path {
+  stroke: var(--ring);
+  stroke-width: 2.5;
+}
+.pretui-node-canvas .boxel-canvas__controls {
+  border-radius: var(--pretui-canvas-chrome-radius, 8px);
+  overflow: hidden;
+}
+.pretui-node-canvas .boxel-canvas__controls-button {
+  height: var(--pretui-canvas-chrome-size, 26px);
+  width: var(--pretui-canvas-chrome-size, 26px);
+}
+.pretui-node-canvas .boxel-canvas__controls-button:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: -2px;
+  position: relative;
+  z-index: 1;
+}
+.pretui-node-canvas .boxel-canvas__minimap {
+  border-radius: var(--pretui-canvas-chrome-radius, 8px);
+  overflow: hidden;
+  box-shadow: var(--pretui-canvas-chrome-shadow,
+    0 0 0 1px var(--border), 0 1px 2px rgb(0 0 0 / 0.12));
+}
+.pretui-node-canvas .boxel-canvas__handle {
+  width: var(--pretui-handle-size, 8px);
+  height: var(--pretui-handle-size, 8px);
+  transition: box-shadow 140ms ease, background-color 140ms ease;
+}
+.pretui-node-canvas .boxel-canvas__handle.connectionindicator:hover {
+  box-shadow: 0 0 0 4px color-mix(in oklch,
+    var(--primary) 22%, transparent);
+}
+.pretui-node-canvas[data-summary='visible'] .boxel-canvas__panel.bottom {
+  bottom: var(--pretui-canvas-summary-height, 8rem);
+}
+@media (prefers-reduced-motion: reduce) {
+  .pretui-node-canvas .boxel-canvas__edge.animated .boxel-canvas__edge-path {
+    animation: none;
+    stroke-dashoffset: 0;
+  }
+  .pretui-node-canvas .boxel-canvas__connection .animated {
+    animation: none;
+    stroke-dashoffset: 0;
+  }
+  .pretui-node-canvas .boxel-canvas__handle {
+    transition: none;
+  }
+}
+`;
+
+// ── The arrowhead bug this fixes ─────────────────────────────────────────
+// boxel-canvas emits `marker-end="url('#1__type=arrowclosed')"` on any edge
+// carrying `markerEnd` — and there is not ONE `<marker>` element anywhere
+// in the package. React Flow renders a `<MarkerDefinitions>` component into
+// its flow SVG; the Ember port never ported it, so `markerEnd` resolves to
+// a dangling fragment reference and draws NOTHING, silently. A directed
+// graph with no arrowheads is ambiguous — you cannot tell which way an
+// edge runs — so the defs are supplied here.
+//
+// The engine hard-codes the `1__` prefix (a flow-id placeholder that was
+// never wired), which means the ids are document-global whether we like it
+// or not. So they are injected ONCE per document, refcounted alongside the
+// stylesheets, rather than per canvas. `context-stroke` makes each
+// arrowhead take the colour of the edge that references it, so a selected
+// edge gets a selected arrowhead for free and no token has to be resolved
+// from outside the canvas's own subtree.
+const MARKERS_ID = 'pretui-surfaces-canvas-markers';
+const MARKER_SVG = `<defs>
+<marker id="1__type=arrowclosed" markerWidth="12.5" markerHeight="12.5" viewBox="-10 -10 20 20" markerUnits="strokeWidth" orient="auto-start-reverse" refX="0" refY="0">
+<polyline points="-5,-4 0,0 -5,4 -5,-4" fill="context-stroke" stroke="context-stroke" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"></polyline>
+</marker>
+<marker id="1__type=arrow" markerWidth="12.5" markerHeight="12.5" viewBox="-10 -10 20 20" markerUnits="strokeWidth" orient="auto-start-reverse" refX="0" refY="0">
+<polyline points="-5,-4 0,0 -5,4" fill="none" stroke="context-stroke" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"></polyline>
+</marker>
+</defs>`;
+
+function retainMarkers() {
+  let el = document.getElementById(MARKERS_ID);
+  if (!el) {
+    let svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    svg.id = MARKERS_ID;
+    svg.setAttribute('aria-hidden', 'true');
+    svg.setAttribute('width', '0');
+    svg.setAttribute('height', '0');
+    svg.style.position = 'absolute';
+    svg.innerHTML = MARKER_SVG;
+    document.body.appendChild(svg);
+    el = svg as unknown as HTMLElement;
+  }
+  el.dataset['refs'] = String(Number(el.dataset['refs'] ?? '0') + 1);
+}
+
+function releaseMarkers() {
+  let el = document.getElementById(MARKERS_ID);
+  if (!el) {
+    return;
+  }
+  let remaining = Number(el.dataset['refs'] ?? '1') - 1;
+  if (remaining <= 0) {
+    el.remove();
+  } else {
+    el.dataset['refs'] = String(remaining);
+  }
+}
+
+function retainSheet(id: string, css: string) {
+  let el: HTMLElement | null = document.getElementById(id);
+  if (!el) {
+    let style = document.createElement('style');
+    style.id = id;
+    style.textContent = css;
+    document.head.appendChild(style);
+    el = style;
+  }
+  el.dataset['refs'] = String(Number(el.dataset['refs'] ?? '0') + 1);
+}
+
+function releaseSheet(id: string) {
+  let el: HTMLElement | null = document.getElementById(id);
+  if (!el) {
+    return;
+  }
+  let remaining = Number(el.dataset['refs'] ?? '1') - 1;
+  if (remaining <= 0) {
+    el.remove();
+  } else {
+    el.dataset['refs'] = String(remaining);
+  }
+}
+
+/**
+ * Mounts the boxel-canvas engine stylesheet, the Pretui skin, and the
+ * arrowhead marker defs the engine references but never ships, for as long
+ * as the modified element is alive. Refcounted: many canvases share one set
+ * and the last teardown removes it. Use it on any element that hosts a
+ * `<Canvas>` from `./surfaces/canvas/index.js`.
+ */
+export const canvasStylesheet = modifier(() => {
+  retainSheet(ENGINE_SHEET_ID, CANVAS_CSS);
+  retainSheet(SKIN_SHEET_ID, PRETUI_CANVAS_SKIN);
+  retainMarkers();
+  return () => {
+    releaseMarkers();
+    releaseSheet(SKIN_SHEET_ID);
+    releaseSheet(ENGINE_SHEET_ID);
+  };
+});
+
+// ── Shared data shapes ───────────────────────────────────────────────────
+
+/** Payload a NodeCard reads. Any extra keys are yours to use in a custom body. */
+export interface NodeCardData {
+  /** headline line — the one thing a reader scans for */
+  title?: string;
+  /** machine value (id / version / enum) set as a Token, per Law 3 */
+  kind?: string;
+  /** one supporting line under the title */
+  meta?: string;
+  /** short state word; its hue is DERIVED from the string, per Law 2 */
+  status?: string;
+  /** override the derived hue with an explicit color/`var()` */
+  hue?: string;
+  /** engine fallback: bare label when no title is given */
+  label?: string;
+  [key: string]: unknown;
+}
+
+/** One node. `position` is graph space; the engine owns it after a drag. */
+export interface CanvasNode {
+  id: string;
+  position: { x: number; y: number };
+  data?: NodeCardData;
+  /** node-type key into `@nodeTypes`; defaults to Pretui's own shell */
+  type?: string;
+  width?: number;
+  height?: number;
+  sourcePosition?: 'left' | 'right' | 'top' | 'bottom';
+  targetPosition?: 'left' | 'right' | 'top' | 'bottom';
+  selected?: boolean;
+  draggable?: boolean;
+  selectable?: boolean;
+  focusable?: boolean;
+  hidden?: boolean;
+  /** screen-reader name; NodeCanvas fills it from data.title when absent */
+  ariaLabel?: string;
+  [key: string]: unknown;
+}
+
+/** One edge. `animated` dashes the stroke (and is silenced under reduced motion). */
+export interface CanvasEdge {
+  id: string;
+  source: string;
+  target: string;
+  label?: string;
+  animated?: boolean;
+  selected?: boolean;
+  type?: string;
+  [key: string]: unknown;
+}

package/bundled-realms/pretui/internal/texture.gts

@@ -0,0 +1,81 @@
+// Pretui — TEXTURE territory. Three components: BackgroundField (the
+// consolidated ambient-field catalogue), Backdrop (the scrim under layered
+// surfaces), PulsingBorder (the "this is live" boundary, shipped WITH its
+// text affordance).
+//
+// Law 6 governs this whole file: texture never carries information. Every
+// painted layer here is `aria-hidden`, `pointer-events: none`, and never the
+// sole carrier of meaning. The one borderline case the matrix calls out —
+// "pulsing border" = "this is live" — ships the affordance in the component
+// rather than trusting the caller to bolt one on.
+//
+// Law 9 governs the implementation: `pretui/texture` vendors NO engine. No
+// WebGL, no ogl, no three, no paper-shaders, no canvas paint loop, no
+// requestAnimationFrame. Everything below is gradients, masks, transforms
+// and @keyframes. A card rendering an invoice pays for nothing.
+//
+// What the inspiration got wrong, and what this file does instead:
+//
+//   * react-bits ships **55 separate background components** (Aurora, Beams,
+//     DotGrid, GradientWaves, Grainient, LightRays, Plasma, Waves, …), most
+//     of them dragging in ogl/WebGL; cult-ui ships a parallel `bg-*` /
+//     `hero-*` family; fancy ships AnimatedGradientWithSvg. Fifty-five import
+//     paths, fifty-five prop surfaces, fifty-five bundles. Pretui ships ONE
+//     component with a `@variant` knob naming a compiled catalogue. The
+//     consolidation IS the improvement: one signature to learn, one set of
+//     knobs (scale / opacity / hue / speed / fade) that means the same thing
+//     in every field, and one place where the reduced-motion and token rules
+//     are enforced.
+//   * Upstream backgrounds hardcode their palettes (`#7cff67`, `rgba(255,
+//     255,255,.08)`) or fork on `dark:`. Every field here rides theme tokens
+//     (`--chart-1…5`, `--foreground`, `--background`) through
+//     `color-mix()`, so a field re-tints with the theme and with light/dark
+//     automatically. There is not one dark branch in this file.
+//   * Upstream animates `background-position` (a full repaint of a
+//     viewport-sized layer, every frame). Here the painted layer is
+//     oversized and only `transform` / `opacity` are animated — compositor
+//     work, no repaint. Tile-drift translations are exactly one tile, so the
+//     loop is seamless.
+//   * Upstream's "reduced motion" story is usually nothing at all. Here the
+//     base rule IS the resting state and the keyframes only supply the
+//     choreography, so `animation: none` is a complete, deliberate-looking
+//     kill switch (Law 5).
+//   * Deliberately NOT ported: everything that needs a shader or a particle
+//     integrator (Galaxy, Plasma, Iridescence, Dither, Particles, Lightfall,
+//     GridDistortion, Balatro…). Those are not expressible in honest CSS and
+//     Law 9 forbids the engine that would make them possible. They are named
+//     here rather than hidden (Law 7).
+//
+// Pretui — shared style helpers for the texture components (BackgroundField, Backdrop, PulsingBorder).
+import { htmlSafe } from '@ember/template';
+import { cssValue as sharedCssValue } from '../pretui-css';
+
+// ── shared helpers ───────────────────────────────────────────────────────
+
+// Args flow into inline custom properties, so caller strings go through the
+// kit-wide allowlist (pretui-css.gts) before they reach htmlSafe.
+//
+// This replaced a local strip-and-continue sanitiser that removed `;{}<>`
+// and kept whatever was left — which let `url(https://evil/x)` through
+// untouched, since it contains none of those characters. Validate-or-drop is
+// the only version of this that holds. `@hue='var(--chart-4)'` (the useful
+// case) is unaffected.
+export function cssValue(value: string | undefined): string | undefined {
+  return sharedCssValue(value);
+}
+
+export function clampNum(
+  value: number | undefined,
+  min: number,
+  max: number,
+): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Number.isFinite(value)) return undefined;
+  return Math.min(Math.max(value, min), max);
+}
+
+export function styleFrom(
+  parts: string[],
+): ReturnType<typeof htmlSafe> | undefined {
+  return parts.length > 0 ? htmlSafe(parts.join('; ')) : undefined;
+}

package/bundled-realms/pretui/internal/toggle-controls-fixtures.gts

@@ -0,0 +1,7 @@
+// Pretui — fixtures shared by the toggle-controls usage pages.
+import { PRETUI_SIZES, PRETUI_TONES } from '../pretui-primitives';
+
+export 
+const TONES = [...PRETUI_TONES];
+
+export const SIZES = [...PRETUI_SIZES];