@ripple-ui/svelte 0.0.0-stage → 0.9.0-next.0

package/dist/utils/mermaid.js

@@ -0,0 +1,144 @@
+// utils/mermaid.ts — Draws mermaid source as SVG for the docs site
+// (site/docs/diagrams.ts) and the markdown widget. Browser only: call it from
+// an effect or an attachment, never at module top level.
+// - mermaid is a dynamic import, fetched the first time anything renders, so a
+//   bundle (or a chat card) with no diagram never loads it.
+// - mermaidConfig maps a palette of opaque hex colours onto mermaid's 'base'
+//   theme in the neo look: rounded nodes with brand (palette.primary) strokes
+//   on a soft card fill, curved (basis) flowchart edges in the soft ink.
+//   Callers resolve their own tokens with resolveColors: mermaid's colour maths
+//   cannot parse oklch or color-mix, so each token is painted over the ground
+//   on a 1px canvas and read back as #rrggbb.
+// - mermaid.initialize is global, and the site and a widget can draw on one
+//   page with different palettes, so every render goes through one promise
+//   chain and re-initializes only when the config changed. securityLevel is
+//   always 'strict'.
+let loading;
+let queue = Promise.resolve();
+let initialized = '';
+let seq = 0;
+/**
+ * CSS colours (any syntax, var() resolved at `scope`) to opaque #rrggbb, each
+ * painted over `ground` (itself over the page background). Null without a 2D canvas.
+ */
+export function resolveColors(css, scope = document.body, ground = 'var(--background, Canvas)') {
+    const ctx = document.createElement('canvas').getContext('2d', { willReadFrequently: true });
+    if (!ctx)
+        return null;
+    const probe = document.createElement('span');
+    probe.style.display = 'none';
+    scope.append(probe);
+    const computed = (value) => {
+        probe.style.color = '';
+        probe.style.color = value;
+        return getComputedStyle(probe).color;
+    };
+    const layers = [computed('var(--background, Canvas)'), computed(ground)];
+    const out = {};
+    for (const key of Object.keys(css)) {
+        for (const fill of [...layers, computed(css[key])]) {
+            ctx.fillStyle = fill;
+            ctx.fillRect(0, 0, 1, 1);
+        }
+        const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+        out[key] = `#${[r, g, b].map((n) => n.toString(16).padStart(2, '0')).join('')}`;
+    }
+    probe.remove();
+    return out;
+}
+/** True when a #rrggbb colour is dark (relative luminance under 0.4). */
+export function isDarkHex(hex) {
+    const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.4;
+}
+/**
+ * mermaid's config for one palette. `htmlLabels: false` keeps labels as SVG
+ * text (no foreignObject), which a caller drawing untrusted source needs so it
+ * can run the result through an SVG sanitizer.
+ */
+export function mermaidConfig(c, font, { htmlLabels = true } = {}) {
+    return {
+        startOnLoad: false,
+        securityLevel: 'strict',
+        suppressErrorRendering: true,
+        theme: 'base',
+        fontFamily: font,
+        htmlLabels,
+        look: 'neo',
+        // mermaid 12 defaults to elk, which forces orthogonal edges; dagre honours `curve`.
+        layout: 'dagre',
+        // Rounded nodes even where the neo look keeps a square shape; lives in the SVG's own <style>.
+        themeCSS: '.node rect, .cluster rect { rx: 10px; ry: 10px; } .edgePath .path, .flowchart-link { stroke-width: 1.5px; }',
+        flowchart: { wrappingWidth: 260, htmlLabels, curve: 'basis', nodeSpacing: 36, rankSpacing: 44, padding: 14 },
+        sequence: { actorFontFamily: font, messageFontFamily: font, noteFontFamily: font },
+        themeVariables: {
+            darkMode: isDarkHex(c.ground),
+            fontFamily: font,
+            fontSize: '14px',
+            background: c.ground,
+            textColor: c.ink,
+            titleColor: c.ink,
+            lineColor: c.soft,
+            primaryColor: c.card,
+            primaryTextColor: c.ink,
+            primaryBorderColor: c.primary,
+            secondaryColor: c.inset,
+            secondaryTextColor: c.ink,
+            secondaryBorderColor: c.border,
+            tertiaryColor: c.panel,
+            tertiaryTextColor: c.ink,
+            tertiaryBorderColor: c.border,
+            mainBkg: c.card,
+            nodeBorder: c.primary,
+            nodeTextColor: c.ink,
+            clusterBkg: c.panel,
+            clusterBorder: c.border,
+            arrowheadColor: c.soft,
+            edgeLabelBackground: c.ground,
+            actorBkg: c.tint,
+            actorBorder: c.primary,
+            actorTextColor: c.ink,
+            actorLineColor: c.border,
+            signalColor: c.soft,
+            signalTextColor: c.ink,
+            labelBoxBkgColor: c.card,
+            labelBoxBorderColor: c.border,
+            labelTextColor: c.ink,
+            loopTextColor: c.ink,
+            noteBkgColor: c.inset,
+            noteTextColor: c.ink,
+            noteBorderColor: c.border,
+            activationBkgColor: c.tint,
+            activationBorderColor: c.primary,
+            sequenceNumberColor: c.onPrimary,
+            stateBkg: c.card,
+            stateLabelColor: c.ink,
+            stateBorder: c.border,
+            labelColor: c.ink,
+            transitionColor: c.soft,
+            transitionLabelColor: c.ink,
+            compositeBackground: c.panel,
+            compositeTitleBackground: c.card,
+            altBackground: c.inset,
+            specialStateColor: c.primary,
+            innerEndBackground: c.primary
+        }
+    };
+}
+/** Render mermaid `source` to an SVG string. Rejects when the source does not parse. */
+export function renderMermaid(source, config) {
+    loading ??= import('mermaid').then((m) => m.default);
+    const run = queue.then(async () => {
+        const mermaid = await loading;
+        await document.fonts?.ready;
+        const key = JSON.stringify(config);
+        if (key !== initialized) {
+            mermaid.initialize(config);
+            initialized = key;
+        }
+        const { svg } = await mermaid.render(`ripple-mermaid-${++seq}`, source);
+        return svg;
+    });
+    queue = run.catch(() => { });
+    return run;
+}

package/dist/utils/safe-color.d.ts

@@ -0,0 +1,4 @@
+export declare const COLOR_RE: RegExp;
+export declare const safeColor: (raw: string | undefined, fallback: string) => string;
+/** A colour literal or a `var(--ripple-*)` token, else undefined. Never throws. */
+export declare function safeThemeColor(raw: unknown): string | undefined;

package/dist/utils/safe-color.js

@@ -0,0 +1,18 @@
+// utils/safe-color.ts: the colour allowlist for spec-controlled colour props.
+// A colour from a spec is model output and may land in an attribute, a style
+// declaration or a generator that concatenates strings (Qr), so only literals
+// that cannot terminate either are let through: hex, rgb/rgba/hsl/hsla
+// functional forms and bare keywords. Anything else falls back.
+// `safeThemeColor` also admits a Ripple token reference, `var(--ripple-name)`,
+// for widgets that paint through CSS (Gauge); Qr keeps the strict set because
+// its generator cannot resolve a custom property.
+export const COLOR_RE = /^(#[0-9a-f]{3,8}|[a-z]+|(rgb|rgba|hsl|hsla)\([0-9a-z%.,\s/]+\))$/i;
+const TOKEN_RE = /^var\(--ripple-[a-z0-9-]+\)$/i;
+export const safeColor = (raw, fallback) => raw && COLOR_RE.test(raw.trim()) ? raw.trim() : fallback;
+/** A colour literal or a `var(--ripple-*)` token, else undefined. Never throws. */
+export function safeThemeColor(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const c = raw.trim();
+    return c && (COLOR_RE.test(c) || TOKEN_RE.test(c)) ? c : undefined;
+}

package/dist/utils/safe-props.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @file safe-props.ts
+ * @changes 2026-09-17: shortSample's circular-object fallback is a literal
+ *   '[unserializable]' and option labels coerce via asText (objects → JSON,
+ *   not "[object Object]") — oxlint no-base-to-string sweep.
+ * @description Defensive guards for widget props consumed as arrays/objects.
+ *
+ * Ripple specs are LLM-generated. The expression resolver silently returns
+ * `undefined` (or a literal string) when it can't parse a fragment — so a
+ * `prop.map(...)` call on the receiving widget will throw and crash the
+ * entire panel. These helpers absorb that failure mode: if the prop isn't
+ * the expected shape we return a safe empty value and warn once.
+ *
+ * Pattern in widgets:
+ *   const safeOptions = $derived(safeArray(options, { widget: 'select', key: 'options' }));
+ *   const safeData    = $derived(safeObject(data,    { widget: 'kvtable', key: 'data' }));
+ *
+ * The `widget` / `key` context is what makes the warnings useful — without
+ * them you only see a stack trace deep inside Svelte runtime.
+ */
+interface Ctx {
+    widget?: string;
+    key?: string;
+}
+/**
+ * Detail payload of the `ripple:bad-prop` CustomEvent fired on
+ * `document` whenever a defensive guard hits a non-conforming prop.
+ *
+ * Host applications can listen for these to pipe spec-quality
+ * problems into Sentry / Datadog / a dashboard:
+ *
+ *     document.addEventListener('ripple:bad-prop', (e) => {
+ *       const d = (e as CustomEvent<RippleBadPropDetail>).detail;
+ *       sendTelemetry('ripple.bad_prop', d);
+ *     });
+ *
+ * The same dedupe rules that throttle console warnings also throttle
+ * events, so listeners get one signal per unique offending value.
+ */
+export interface RippleBadPropDetail {
+    widget?: string;
+    key?: string;
+    expected: 'array' | 'object' | 'function';
+    receivedType: string;
+    /** Best-effort sample of the bad value for inspection; primitives
+     *  pass through, objects are stringified with a short cap. */
+    sample: unknown;
+}
+/** Coerce to array. Returns [] for non-arrays and warns once with context. */
+export declare function safeArray<T = unknown>(v: unknown, ctx?: Ctx): T[];
+/** Coerce to plain object. Returns {} for non-objects and warns once. */
+export declare function safeObject<T extends Record<string, unknown> = Record<string, unknown>>(v: unknown, ctx?: Ctx): T;
+/** Coerce to function. Returns a no-op for non-functions and warns once. */
+export declare function safeFn<F extends (...args: never[]) => unknown>(v: unknown, ctx?: Ctx): F;
+/**
+ * Coerce a single choice-widget option into the canonical
+ * `{value, label}` shape. Accepts:
+ *
+ *   - a primitive (string / number) — used as both value and label,
+ *   - an object with `value` and `label` (passed through),
+ *   - an object with one of the common alias keys: value ← `id`/`key`,
+ *     label ← `name`/`title`/`text`.
+ *
+ * This is what lets a `workspace.members` `$source` (which returns
+ * `{id, name, email, ...}`) bind directly to a `<select>` / `<radio-group>`
+ * / `<segmented>` / `<combobox>` / `<multi-select>` without a manual
+ * mapping step the resolver couldn't express anyway.
+ *
+ * Pass-through extra fields are preserved so widgets that look at e.g.
+ * `description` or `disabled` keep working.
+ */
+export interface CanonicalOption {
+    value: string | number;
+    label: string;
+    [k: string]: unknown;
+}
+export declare function toCanonicalOption(raw: unknown): CanonicalOption | null;
+/**
+ * Map an unknown options array into canonical `{value, label}` shape,
+ * dropping any item that can't be coerced, and any later option whose value
+ * repeats an earlier one (compared as strings, so 1 and '1' collapse too).
+ * Choice widgets key their {#each} by value, and a repeated value from the
+ * model would throw `each_key_duplicate`; two options with one value were one
+ * choice anyway. Use in choice widgets:
+ *
+ *     const normalized = $derived(canonicalOptions(options, { widget: 'select', key: 'options' }));
+ */
+export declare function canonicalOptions(v: unknown, ctx?: Ctx): CanonicalOption[];
+/**
+ * One each-key per item, unique even when the model repeats an id: the first
+ * `a` keys as `a`, later ones as `a#1`, `a#2` (skipping any key already taken).
+ * Use as `{#each items as item, i (keys[i])}` with `keys` derived alongside
+ * the list, so a repeated id renders both items instead of throwing
+ * `each_key_duplicate`. Unlike canonicalOptions, nothing is dropped.
+ */
+export declare function uniqueKeys<T>(items: readonly T[], getId: (item: T, i: number) => unknown): string[];
+export {};

package/dist/utils/safe-props.js

@@ -0,0 +1,170 @@
+/**
+ * @file safe-props.ts
+ * @changes 2026-09-17: shortSample's circular-object fallback is a literal
+ *   '[unserializable]' and option labels coerce via asText (objects → JSON,
+ *   not "[object Object]") — oxlint no-base-to-string sweep.
+ * @description Defensive guards for widget props consumed as arrays/objects.
+ *
+ * Ripple specs are LLM-generated. The expression resolver silently returns
+ * `undefined` (or a literal string) when it can't parse a fragment — so a
+ * `prop.map(...)` call on the receiving widget will throw and crash the
+ * entire panel. These helpers absorb that failure mode: if the prop isn't
+ * the expected shape we return a safe empty value and warn once.
+ *
+ * Pattern in widgets:
+ *   const safeOptions = $derived(safeArray(options, { widget: 'select', key: 'options' }));
+ *   const safeData    = $derived(safeObject(data,    { widget: 'kvtable', key: 'data' }));
+ *
+ * The `widget` / `key` context is what makes the warnings useful — without
+ * them you only see a stack trace deep inside Svelte runtime.
+ */
+import { asText } from '../widgets/text-coerce.js';
+const warnedRefs = new WeakSet();
+const warnedPrimitives = new Set();
+function describe(v) {
+    if (v === null)
+        return 'null';
+    if (v === undefined)
+        return 'undefined';
+    if (Array.isArray(v))
+        return `Array(${v.length})`;
+    if (typeof v === 'object') {
+        const name = v?.constructor?.name ?? 'Object';
+        return `${name} (not array)`;
+    }
+    if (typeof v === 'string')
+        return `string (${JSON.stringify(v.slice(0, 40))}${v.length > 40 ? '…' : ''})`;
+    return typeof v;
+}
+const EVENT_NAME = 'ripple:bad-prop';
+function shortSample(v) {
+    if (v === null || v === undefined)
+        return v;
+    if (typeof v === 'object') {
+        try {
+            const s = JSON.stringify(v);
+            return s.length > 200 ? s.slice(0, 200) + '…' : s;
+        }
+        catch {
+            return '[unserializable]';
+        }
+    }
+    if (typeof v === 'string')
+        return v.length > 200 ? v.slice(0, 200) + '…' : v;
+    return v;
+}
+function dispatchBadProp(v, expected, ctx) {
+    if (typeof document === 'undefined')
+        return;
+    try {
+        const detail = {
+            widget: ctx?.widget,
+            key: ctx?.key,
+            expected,
+            receivedType: describe(v),
+            sample: shortSample(v)
+        };
+        document.dispatchEvent(new CustomEvent(EVENT_NAME, { detail }));
+    }
+    catch {
+        // Defensive: never let telemetry break the renderer.
+    }
+}
+function warnOnce(v, expected, ctx) {
+    // Dedupe: object refs via WeakSet, primitives via stringified key.
+    if (v !== null && typeof v === 'object') {
+        if (warnedRefs.has(v))
+            return;
+        warnedRefs.add(v);
+    }
+    else {
+        const tag = `${ctx?.widget ?? '?'}:${ctx?.key ?? '?'}:${describe(v)}`;
+        if (warnedPrimitives.has(tag))
+            return;
+        warnedPrimitives.add(tag);
+    }
+    const where = ctx ? `<${ctx.widget ?? '?'}> prop "${ctx.key ?? '?'}"` : 'prop';
+    // eslint-disable-next-line no-console
+    console.warn(`[Ripple] ${where} expected ${expected}, got ${describe(v)} — using empty fallback. ` +
+        `Likely cause: the spec expression could not be evaluated by the resolver.`, v);
+    dispatchBadProp(v, expected, ctx);
+}
+/** Coerce to array. Returns [] for non-arrays and warns once with context. */
+export function safeArray(v, ctx) {
+    if (Array.isArray(v))
+        return v;
+    if (v !== undefined && v !== null && ctx)
+        warnOnce(v, 'array', ctx);
+    return [];
+}
+/** Coerce to plain object. Returns {} for non-objects and warns once. */
+export function safeObject(v, ctx) {
+    if (v !== null && typeof v === 'object' && !Array.isArray(v))
+        return v;
+    if (v !== undefined && v !== null && ctx)
+        warnOnce(v, 'object', ctx);
+    return {};
+}
+/** Coerce to function. Returns a no-op for non-functions and warns once. */
+export function safeFn(v, ctx) {
+    if (typeof v === 'function')
+        return v;
+    if (v !== undefined && v !== null && ctx)
+        warnOnce(v, 'function', ctx);
+    return ((..._args) => undefined);
+}
+export function toCanonicalOption(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw === 'string' || typeof raw === 'number') {
+        return { value: raw, label: String(raw) };
+    }
+    if (typeof raw !== 'object')
+        return null;
+    const o = raw;
+    const value = (o.value ?? o.id ?? o.key);
+    const labelRaw = o.label ?? o.name ?? o.title ?? o.text ?? value;
+    if (value === undefined || value === null)
+        return null;
+    const label = labelRaw === undefined || labelRaw === null ? String(value) : asText(labelRaw);
+    return { ...o, value, label };
+}
+/**
+ * Map an unknown options array into canonical `{value, label}` shape,
+ * dropping any item that can't be coerced, and any later option whose value
+ * repeats an earlier one (compared as strings, so 1 and '1' collapse too).
+ * Choice widgets key their {#each} by value, and a repeated value from the
+ * model would throw `each_key_duplicate`; two options with one value were one
+ * choice anyway. Use in choice widgets:
+ *
+ *     const normalized = $derived(canonicalOptions(options, { widget: 'select', key: 'options' }));
+ */
+export function canonicalOptions(v, ctx) {
+    const seen = new Set();
+    return safeArray(v, ctx)
+        .map((item) => toCanonicalOption(item))
+        .filter((o) => {
+        if (o === null || seen.has(String(o.value)))
+            return false;
+        seen.add(String(o.value));
+        return true;
+    });
+}
+/**
+ * One each-key per item, unique even when the model repeats an id: the first
+ * `a` keys as `a`, later ones as `a#1`, `a#2` (skipping any key already taken).
+ * Use as `{#each items as item, i (keys[i])}` with `keys` derived alongside
+ * the list, so a repeated id renders both items instead of throwing
+ * `each_key_duplicate`. Unlike canonicalOptions, nothing is dropped.
+ */
+export function uniqueKeys(items, getId) {
+    const seen = new Set();
+    return items.map((item, i) => {
+        const id = String(getId(item, i));
+        let key = id;
+        for (let n = 1; seen.has(key); n++)
+            key = `${id}#${n}`;
+        seen.add(key);
+        return key;
+    });
+}

package/dist/utils/sanitize-html.d.ts

@@ -0,0 +1,14 @@
+export declare function sanitizeHtml(html: string): string;
+/**
+ * Sanitize a generated-SVG string (e.g. qrcode-svg output) for {@html}.
+ * Defense in depth behind input validation — the generator's inputs must still
+ * be constrained (see Qr.svelte's safeColor), because a sanitizer pass can't
+ * fix a generator that interpolates attacker text into markup.
+ */
+export declare function sanitizeSvg(svg: string): string;
+/**
+ * Sanitize generated MathML (temml output) for insertion. `style` is dropped
+ * like everywhere else: it only carries \color and a few spacing tweaks, and
+ * keeping it would reopen the url() beacon channel.
+ */
+export declare function sanitizeMath(mathml: string): string;

package/dist/utils/sanitize-html.js

@@ -0,0 +1,62 @@
+// utils/sanitize-html.ts — sanitize HTML/SVG strings before they reach {@html}.
+//
+// Ripple widgets (Markdown, RichTextDisplay) render SPEC-CONTROLLED strings via
+// {@html}. Specs can be LLM-generated and prompt-injected (untrusted) — e.g. an
+// agent that read a malicious page emits `{type:"markdown", content:"<img src=x
+// onerror=…>"}`. Rendered raw, that is XSS in the host origin. This runs the HTML
+// through DOMPurify's HTML profile: benign structural markup (headings, lists,
+// links, images, tables, code) survives; <script>, on* handlers, and javascript:
+// URIs are stripped. `style` is forbidden on top of the profile — spec content
+// never needs inline CSS, and `style` is an exfil / UI-redress channel:
+// url(https://evil/...) beacons on render, and position:fixed can overlay the
+// host app with a fake credential prompt. Structural markup is unaffected.
+//
+// sanitizeMath is the MathML-profile sibling for temml output (the markdown
+// widget's math); the HTML profile would delete the <math> element outright.
+//
+// sanitizeSvg is the SVG-profile sibling for widgets that {@html} generated SVG
+// (Qr): the HTML profile would delete the <svg> element outright.
+//
+// Client-guarded: DOMPurify needs a DOM. This FAILS OPEN under SSR — the input
+// is returned unchanged. That is safe only because ripple's untrusted surface
+// (chat) is client-rendered; Svelte 5 does NOT re-sanitize on hydration (it
+// adopts server markup as-is and deliberately does not repair mismatches — see
+// svelte internal/client/dom/blocks/html.js). If untrusted content ever renders
+// through SSR, this guard must become a server-side sanitizer
+// (isomorphic-dompurify / jsdom) instead.
+import DOMPurify from 'dompurify';
+export function sanitizeHtml(html) {
+    if (!html)
+        return '';
+    if (typeof window === 'undefined')
+        return html; // SSR fail-open — see header
+    return DOMPurify.sanitize(html, {
+        USE_PROFILES: { html: true },
+        FORBID_ATTR: ['style']
+    });
+}
+/**
+ * Sanitize a generated-SVG string (e.g. qrcode-svg output) for {@html}.
+ * Defense in depth behind input validation — the generator's inputs must still
+ * be constrained (see Qr.svelte's safeColor), because a sanitizer pass can't
+ * fix a generator that interpolates attacker text into markup.
+ */
+export function sanitizeSvg(svg) {
+    if (!svg)
+        return '';
+    if (typeof window === 'undefined')
+        return svg; // SSR fail-open — see header
+    return DOMPurify.sanitize(svg, { USE_PROFILES: { svg: true, svgFilters: true } });
+}
+/**
+ * Sanitize generated MathML (temml output) for insertion. `style` is dropped
+ * like everywhere else: it only carries \color and a few spacing tweaks, and
+ * keeping it would reopen the url() beacon channel.
+ */
+export function sanitizeMath(mathml) {
+    if (!mathml)
+        return '';
+    if (typeof window === 'undefined')
+        return mathml; // SSR fail-open, see header
+    return DOMPurify.sanitize(mathml, { USE_PROFILES: { mathMl: true }, FORBID_ATTR: ['style'] });
+}

package/dist/utils/url-sanitizer.d.ts

@@ -0,0 +1,2 @@
+/** A safe href for `raw`, or null when it is empty or uses a disallowed scheme. */
+export declare function safeHref(raw: string | undefined | null): string | null;

package/dist/utils/url-sanitizer.js

@@ -0,0 +1,9 @@
+// url-sanitizer.ts — `safeHref`, the null-returning form of `safeUrl` from
+// @ripple-ui/core for sinks that branch on "is there a link" (the table link
+// column, C4 kb links). It delegates to the one URL allowlist, so both reject
+// javascript:/vbscript:/data:/file: the same way.
+import { safeUrl } from '@ripple-ui/core';
+/** A safe href for `raw`, or null when it is empty or uses a disallowed scheme. */
+export function safeHref(raw) {
+    return safeUrl(raw) ?? null;
+}

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+import { type ClassValue } from 'clsx';
+export declare function cn(...inputs: ClassValue[]): string;
+export type WithoutChild<T> = T extends {
+    child?: any;
+} ? Omit<T, "child"> : T;
+export type WithoutChildren<T> = T extends {
+    children?: any;
+} ? Omit<T, "children"> : T;
+export type WithoutChildrenOrChild<T> = WithoutChildren<WithoutChild<T>>;
+export type WithElementRef<T, U extends HTMLElement = HTMLElement> = T & {
+    ref?: U | null;
+};

package/dist/utils.js

@@ -0,0 +1,13 @@
+// utils.ts — shared helpers for the component library.
+// 2026-09-14: `cn` is the canonical shadcn form again — twMerge(clsx(...)).
+// It was clsx alone, which concatenates without resolving Tailwind conflicts,
+// so a caller's `w-[220px]`, `z-[100]` or `text-xs` fought the component's base
+// class and the winner came down to the order Tailwind happened to emit the
+// stylesheet in. tailwind-merge was already a declared dependency and simply
+// unused. This removes the need for per-component regex workarounds (the
+// `defaultWidth` special case in dialog-content.svelte is deleted with it).
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}

package/dist/vendor-modules.d.ts

@@ -0,0 +1,42 @@
+// src/lib/vendor-modules.d.ts
+// Ambient declarations for third-party packages that ship no TypeScript types.
+// Qr.svelte `await import`s `qrcode-svg` at runtime; under `strict`/`noImplicitAny`
+// svelte-check flags the untyped module, and there is no @types package, so it
+// is declared here as `any`. `d3-sankey` has no @types package in the tree;
+// sankey-layout.ts uses only its layout (`sankey`, `sankeyLeft`) and the node
+// and link fields declared below.
+
+declare module 'qrcode-svg';
+
+declare module 'd3-sankey' {
+	export interface SankeyNode {
+		index: number;
+		depth: number;
+		value: number;
+		x0: number;
+		x1: number;
+		y0: number;
+		y1: number;
+	}
+	export interface SankeyLink {
+		source: SankeyNode;
+		target: SankeyNode;
+		value: number;
+		index: number;
+		y0: number;
+		y1: number;
+		width: number;
+	}
+	export interface SankeyLayout {
+		(graph: { nodes: object[]; links: { source: number; target: number; value: number }[] }): {
+			nodes: SankeyNode[];
+			links: SankeyLink[];
+		};
+		nodeAlign(f: (node: SankeyNode, n: number) => number): SankeyLayout;
+		nodeWidth(w: number): SankeyLayout;
+		nodePadding(p: number): SankeyLayout;
+		extent(e: [[number, number], [number, number]]): SankeyLayout;
+	}
+	export function sankey(): SankeyLayout;
+	export function sankeyLeft(node: SankeyNode, n: number): number;
+}

package/dist/version.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file version.ts
+ * @description Single source of truth for the Ripple library version, as a
+ *   plain TS constant. The manifest used to read this via
+ *   `import pkg from '../../../package.json'`, but the manifest is a CLIENT
+ *   module (the visual editor is its first browser consumer), and pulling the
+ *   project-root package.json into the client path trips Vite's
+ *   `server.fs.allow` guard and 500s `vite dev` (most visible in a worktree
+ *   checkout). A plain constant works in BOTH places the version is needed: the
+ *   browser bundle AND the out-of-Vite bun build script
+ *   (scripts/build-manifest.ts) — unlike a Vite `define`, which would be
+ *   undefined under bun. version.test.ts asserts this stays in lockstep with
+ *   package.json so a release bump can't silently drift.
+ * Released versions: svelte 0.9.0-next.0 with core 0.6.1-next.0 (pre-release, npm dist-tag next), embed 0.1.0 and react 0.1.0. A bump
+ *   changes this constant and packages/svelte/package.json together.
+ */
+export declare const RIPPLE_VERSION = "0.9.0-next.0";

package/dist/version.js

@@ -0,0 +1,17 @@
+/**
+ * @file version.ts
+ * @description Single source of truth for the Ripple library version, as a
+ *   plain TS constant. The manifest used to read this via
+ *   `import pkg from '../../../package.json'`, but the manifest is a CLIENT
+ *   module (the visual editor is its first browser consumer), and pulling the
+ *   project-root package.json into the client path trips Vite's
+ *   `server.fs.allow` guard and 500s `vite dev` (most visible in a worktree
+ *   checkout). A plain constant works in BOTH places the version is needed: the
+ *   browser bundle AND the out-of-Vite bun build script
+ *   (scripts/build-manifest.ts) — unlike a Vite `define`, which would be
+ *   undefined under bun. version.test.ts asserts this stays in lockstep with
+ *   package.json so a release bump can't silently drift.
+ * Released versions: svelte 0.9.0-next.0 with core 0.6.1-next.0 (pre-release, npm dist-tag next), embed 0.1.0 and react 0.1.0. A bump
+ *   changes this constant and packages/svelte/package.json together.
+ */
+export const RIPPLE_VERSION = '0.9.0-next.0';