@fiodos/web-core 0.1.0

package/dist/esm/orb/orbView.d.ts

@@ -0,0 +1,56 @@
+/**
+ * orbView — framework-free DOM builders that render the Fiodos orb EXACTLY like
+ * the reference (React Native QuickBite) and @fiodos/react's <OrbSphere />.
+ *
+ * Every visual reuses the SAME @fiodos/core math (double-border layout, fill /
+ * inner-border color resolution, brand-mark bars, keyboard-chip icon specs), so
+ * the embedded vanilla orb matches the dashboard preview, React and React Native
+ * pixel-for-pixel — no "basic circle" divergence. Vue / Svelte / Angular mount
+ * THIS orb through createFiodosAgent → mountOrb.
+ */
+import { type KeyboardChipIcon } from '@fiodos/core';
+/** Visual appearance of the orb — the subset needed to render the sphere. */
+export interface OrbAppearance {
+    accentColor: string;
+    backgroundColor: string;
+    glowColor?: string;
+    colorKey?: string;
+    glowIntensity?: number;
+    innerBorderColor?: string;
+    innerBorderWidth?: number;
+    size: number;
+    waveformColor?: string;
+    logoDataUrl?: string | null;
+}
+/** Keyboard-chip theme (published from the dashboard). */
+export interface ChipTheme {
+    size?: number;
+    shape?: 'circle' | 'rounded' | 'square';
+    backgroundColor?: string;
+    borderColor?: string;
+    iconColor?: string;
+    icon?: KeyboardChipIcon;
+    iconImageDataUrl?: string | null;
+    iconScale?: number;
+    innerBorderColor?: string;
+    innerBorderWidth?: number;
+    borderWidth?: number;
+}
+export declare const DEFAULT_ORB_APPEARANCE: OrbAppearance;
+export type OrbVisualState = 'idle' | 'listening' | 'thinking' | 'speaking';
+/** Builds the keyboard chip button (port of @fiodos/react's <KeyboardChip />). */
+export declare function buildKeyboardChip(opts: {
+    theme: ChipTheme;
+    accentColor: string;
+    backgroundColor: string;
+    label: string;
+    onClick: () => void;
+}): HTMLButtonElement;
+export interface OrbVisual {
+    /** The outer wrapper element (handles the speaking pulse). */
+    element: HTMLDivElement;
+    applyAppearance(appearance: OrbAppearance): void;
+    applyState(state: OrbVisualState, volume: number): void;
+}
+/** Builds a self-contained orb visual that mirrors @fiodos/react's OrbSphere. */
+export declare function createOrbVisual(initial: OrbAppearance): OrbVisual;

package/dist/esm/orb/orbView.js

@@ -0,0 +1,421 @@
+/**
+ * orbView — framework-free DOM builders that render the Fiodos orb EXACTLY like
+ * the reference (React Native QuickBite) and @fiodos/react's <OrbSphere />.
+ *
+ * Every visual reuses the SAME @fiodos/core math (double-border layout, fill /
+ * inner-border color resolution, brand-mark bars, keyboard-chip icon specs), so
+ * the embedded vanilla orb matches the dashboard preview, React and React Native
+ * pixel-for-pixel — no "basic circle" divergence. Vue / Svelte / Angular mount
+ * THIS orb through createFiodosAgent → mountOrb.
+ */
+import { chipBorderRadius, chipIconBaseSizePx, chipIconCenterOffset, chipIconSpec, computeOutwardBorderLayout, normalizeChipIconScale, normalizeKeyboardChipIcon, orbFillDepthBoxShadow, orbOuterGlowBoxShadow, resolveChipIconColor, resolveFiodosOrbMarkBars, resolveInnerBorderColor, resolveOrbBackgroundColor, } from '@fiodos/core';
+const SVG_NS = 'http://www.w3.org/2000/svg';
+export const DEFAULT_ORB_APPEARANCE = {
+    accentColor: '#4f8cff',
+    backgroundColor: '#1b2a4a',
+    colorKey: 'azul',
+    glowIntensity: 100,
+    size: 56,
+};
+function svgEl(tag, attrs) {
+    const el = document.createElementNS(SVG_NS, tag);
+    for (const [k, v] of Object.entries(attrs))
+        el.setAttribute(k, String(v));
+    return el;
+}
+/** Outside → in: exterior glow border, interior hairline ring, then solid fill. */
+function buildDoubleBorder(opts) {
+    const { fillPx, interiorPx, exteriorPx, totalPx, fillRadius, midPx } = computeOutwardBorderLayout(opts.fillDiameter, opts.exteriorWidthSlider, opts.interiorWidthSlider);
+    const isCircle = typeof opts.borderRadius === 'number';
+    const fillRadiusStyle = isCircle ? `${fillRadius}px` : String(opts.borderRadius);
+    const midRadiusStyle = isCircle ? `${midPx / 2}px` : String(opts.borderRadius);
+    const totalRadiusStyle = isCircle ? `${totalPx / 2}px` : String(opts.borderRadius);
+    const outerGlow = opts.outerGlow !== false;
+    const fillDepth = opts.fillDepth !== false;
+    const root = document.createElement('div');
+    Object.assign(root.style, {
+        boxSizing: 'content-box',
+        border: exteriorPx > 0 ? `${exteriorPx}px solid ${opts.exteriorColor}` : '',
+        borderRadius: totalRadiusStyle,
+        background: 'transparent',
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        flexShrink: '0',
+        boxShadow: outerGlow && exteriorPx > 0 ? orbOuterGlowBoxShadow(totalPx, opts.exteriorColor) : '',
+    });
+    const mid = document.createElement('div');
+    Object.assign(mid.style, {
+        boxSizing: 'content-box',
+        border: interiorPx > 0 ? `${interiorPx}px solid ${opts.interiorColor}` : '',
+        borderRadius: midRadiusStyle,
+        background: 'transparent',
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        flexShrink: '0',
+    });
+    const fill = document.createElement('div');
+    Object.assign(fill.style, {
+        width: `${fillPx}px`,
+        height: `${fillPx}px`,
+        borderRadius: fillRadiusStyle,
+        background: opts.fill,
+        overflow: 'hidden',
+        position: 'relative',
+        flexShrink: '0',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        boxShadow: fillDepth && fillPx > 0 ? orbFillDepthBoxShadow(opts.fillDiameter) : '',
+    });
+    mid.appendChild(fill);
+    root.appendChild(mid);
+    return { root, fill };
+}
+// ── Brand mark (port of FiodosOrbMark) ───────────────────────────────────────
+function buildOrbMark(orbSize) {
+    const { bars, color, radius } = resolveFiodosOrbMarkBars(orbSize);
+    const svg = svgEl('svg', {
+        width: orbSize,
+        height: orbSize,
+        viewBox: `0 0 ${orbSize} ${orbSize}`,
+        'aria-hidden': 'true',
+    });
+    svg.style.display = 'block';
+    for (const b of bars) {
+        svg.appendChild(svgEl('rect', { x: b.x, y: b.y, width: b.width, height: b.height, rx: radius, ry: radius, fill: color }));
+    }
+    return svg;
+}
+// ── Waveform (port of VoiceWaveform: 9 bars, bell profile, rAF) ───────────────
+const WAVE_BARS = 9;
+const WAVE_BASE = [0.25, 0.45, 0.65, 0.85, 1.0, 0.85, 0.65, 0.45, 0.25];
+const WAVE_IDLE = [0, 0.7, 1.4, 2.1, 2.8, 2.1, 1.4, 0.7, 0.0];
+const WAVE_REF_HEIGHT = 26;
+function buildWaveform(color, height) {
+    const scale = height / WAVE_REF_HEIGHT;
+    const w = 3 * scale;
+    const g = 3 * scale;
+    const minBarPx = 3 * scale;
+    const el = document.createElement('div');
+    Object.assign(el.style, {
+        display: 'flex',
+        flexDirection: 'row',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: `${g}px`,
+        height: `${height}px`,
+        width: '100%',
+        maxWidth: '88%',
+    });
+    const bars = [];
+    for (let i = 0; i < WAVE_BARS; i++) {
+        const bar = document.createElement('div');
+        Object.assign(bar.style, {
+            width: `${w}px`,
+            height: `${height}px`,
+            borderRadius: `${Math.max(1, 2 * scale)}px`,
+            backgroundColor: color,
+            transformOrigin: 'center center',
+            transform: `scaleY(${minBarPx / height})`,
+            flexShrink: '0',
+        });
+        bars.push(bar);
+        el.appendChild(bar);
+    }
+    let raf = 0;
+    let tick = 0;
+    let last = 0;
+    let volume = 0;
+    const minScale = minBarPx / height;
+    const loop = (now) => {
+        raf = requestAnimationFrame(loop);
+        if (now - last < 80)
+            return;
+        last = now;
+        tick += 0.22;
+        bars.forEach((bar, i) => {
+            let target;
+            if (volume < 0.05) {
+                const sine = (Math.sin(tick + (WAVE_IDLE[i] ?? 0)) + 1) / 2;
+                target = minScale + sine * (0.22 - minScale);
+            }
+            else {
+                const noise = Math.sin(tick * 2.3 + (WAVE_IDLE[i] ?? 0)) * 0.18 + 0.82 + Math.random() * 0.18;
+                target = minScale + volume * (WAVE_BASE[i] ?? 0.5) * (1 - minScale) * noise;
+            }
+            bar.style.transform = `scaleY(${Math.min(1, Math.max(minScale, target))})`;
+        });
+    };
+    return {
+        el,
+        start() {
+            if (raf)
+                return;
+            last = typeof performance !== 'undefined' ? performance.now() : Date.now();
+            raf = requestAnimationFrame(loop);
+        },
+        stop() {
+            if (raf)
+                cancelAnimationFrame(raf);
+            raf = 0;
+        },
+        setVolume(v) {
+            volume = v;
+        },
+    };
+}
+// ── Thinking spinner (port of ThinkingSpinner: 8-bar open arc) ────────────────
+const SPIN_BARS = 8;
+const SPIN_GAP_DEG = 68;
+const SPIN_ARC_SPAN = 360 - SPIN_GAP_DEG;
+const SPIN_ARC_START = SPIN_GAP_DEG / 2;
+const SPIN_OPACITIES = [0.15, 0.25, 0.35, 0.5, 0.65, 0.78, 0.88, 1];
+function buildThinkingSpinner(orbSizePx, color) {
+    const size = Math.max(28, orbSizePx * 0.52);
+    const wrap = document.createElement('div');
+    Object.assign(wrap.style, {
+        position: 'absolute',
+        inset: '0',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        pointerEvents: 'none',
+    });
+    const spin = document.createElement('div');
+    Object.assign(spin.style, {
+        width: `${size}px`,
+        height: `${size}px`,
+        animation: 'fy-spin 0.92s linear infinite',
+    });
+    spin.setAttribute('role', 'progressbar');
+    spin.setAttribute('aria-label', 'Loading');
+    const svg = svgEl('svg', { width: size, height: size, viewBox: '0 0 40 40', 'aria-hidden': 'true' });
+    const step = SPIN_ARC_SPAN / (SPIN_BARS - 1);
+    for (let i = 0; i < SPIN_BARS; i++) {
+        const angle = SPIN_ARC_START + step * i;
+        svg.appendChild(svgEl('rect', {
+            x: '18.25',
+            y: '5.5',
+            width: '3.5',
+            height: '11',
+            rx: '1.75',
+            fill: color,
+            opacity: SPIN_OPACITIES[i] ?? 1,
+            transform: `rotate(${angle} 20 20)`,
+        }));
+    }
+    spin.appendChild(svg);
+    wrap.appendChild(spin);
+    return wrap;
+}
+// ── Keyboard chip icon (port of ChipIconSvg) ──────────────────────────────────
+function buildChipIcon(icon, size, color) {
+    const spec = chipIconSpec(icon);
+    const strokeW = 1.8;
+    const { x: ox, y: oy } = chipIconCenterOffset(spec);
+    const svg = svgEl('svg', { width: size, height: size, viewBox: spec.viewBox, fill: 'none', 'aria-hidden': 'true' });
+    svg.style.display = 'block';
+    svg.style.pointerEvents = 'none';
+    const g = svgEl('g', { transform: `translate(${ox} ${oy})` });
+    if (spec.keyboardFrame && spec.keyDots) {
+        const f = spec.keyboardFrame;
+        g.appendChild(svgEl('rect', { x: f.x, y: f.y, width: f.w, height: f.h, rx: f.rx, stroke: color, 'stroke-width': strokeW }));
+        for (const [cx, cy] of spec.keyDots) {
+            g.appendChild(svgEl('rect', { x: cx - 0.6, y: cy - 0.6, width: 1.2, height: 1.2, rx: 0.2, fill: color }));
+        }
+    }
+    else if (spec.chatFrame && spec.chatLines) {
+        const f = spec.chatFrame;
+        const cx = f.x + f.w / 2;
+        const baseY = f.y + f.h;
+        const lineStroke = Math.max(1.15, strokeW * 0.65);
+        g.appendChild(svgEl('rect', { x: f.x, y: f.y, width: f.w, height: f.h, rx: f.rx, stroke: color, 'stroke-width': strokeW }));
+        if (spec.chatTail) {
+            const t = spec.chatTail;
+            g.appendChild(svgEl('polygon', { points: `${t.left},${baseY} ${t.tipX},${t.tipY} ${t.right},${baseY}`, fill: color }));
+        }
+        for (const { y, w } of spec.chatLines) {
+            g.appendChild(svgEl('line', {
+                x1: cx - w / 2,
+                y1: y,
+                x2: cx + w / 2,
+                y2: y,
+                stroke: color,
+                'stroke-width': lineStroke,
+                'stroke-linecap': 'round',
+            }));
+        }
+    }
+    else {
+        for (const p of spec.paths) {
+            g.appendChild(svgEl('path', {
+                d: p.d,
+                stroke: color,
+                fill: 'none',
+                'stroke-width': strokeW,
+                'stroke-linecap': 'round',
+                'stroke-linejoin': 'round',
+            }));
+        }
+    }
+    svg.appendChild(g);
+    return svg;
+}
+/** Builds the keyboard chip button (port of @fiodos/react's <KeyboardChip />). */
+export function buildKeyboardChip(opts) {
+    const { theme } = opts;
+    const chipSize = theme.size ?? 30;
+    const chipShape = theme.shape ?? 'circle';
+    const radius = chipShape === 'circle' ? '50%' : `${chipBorderRadius(chipShape, chipSize)}px`;
+    const chipBg = theme.backgroundColor ?? opts.backgroundColor;
+    const chipBorder = theme.borderColor ?? opts.accentColor;
+    const chipIconColor = resolveChipIconColor(theme.iconColor, chipBg, opts.accentColor);
+    const chipIconPreset = normalizeKeyboardChipIcon(theme.icon);
+    const chipIconScale = normalizeChipIconScale(theme.iconScale ?? 1);
+    const iconSize = Math.round(chipIconBaseSizePx(chipSize) * chipIconScale);
+    const layout = computeOutwardBorderLayout(chipSize, theme.borderWidth ?? 100, theme.innerBorderWidth);
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.setAttribute('aria-label', opts.label);
+    Object.assign(btn.style, {
+        border: 'none',
+        background: 'transparent',
+        padding: '0',
+        cursor: 'pointer',
+        lineHeight: '0',
+        flexShrink: '0',
+        width: `${layout.totalPx}px`,
+        height: `${layout.totalPx}px`,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+    });
+    btn.onclick = opts.onClick;
+    const { root, fill } = buildDoubleBorder({
+        fillDiameter: chipSize,
+        borderRadius: radius,
+        exteriorColor: chipBorder,
+        exteriorWidthSlider: theme.borderWidth ?? 100,
+        interiorColor: resolveInnerBorderColor(theme.innerBorderColor),
+        interiorWidthSlider: theme.innerBorderWidth,
+        fill: chipBg,
+        outerGlow: false,
+        fillDepth: false,
+    });
+    if (theme.iconImageDataUrl) {
+        const img = document.createElement('img');
+        img.src = theme.iconImageDataUrl;
+        img.alt = '';
+        Object.assign(img.style, {
+            width: `${iconSize}px`,
+            height: `${iconSize}px`,
+            objectFit: 'contain',
+            display: 'block',
+        });
+        fill.appendChild(img);
+    }
+    else {
+        fill.appendChild(buildChipIcon(chipIconPreset, iconSize, chipIconColor));
+    }
+    btn.appendChild(root);
+    return btn;
+}
+/** Builds a self-contained orb visual that mirrors @fiodos/react's OrbSphere. */
+export function createOrbVisual(initial) {
+    const wrapper = document.createElement('div');
+    wrapper.style.display = 'inline-flex';
+    let appearance = initial;
+    let state = 'idle';
+    let volume = 0;
+    let fillEl = null;
+    let waveform = null;
+    function rebuild() {
+        const size = appearance.size ?? DEFAULT_ORB_APPEARANCE.size;
+        const fill = resolveOrbBackgroundColor({
+            colorKey: appearance.colorKey ?? DEFAULT_ORB_APPEARANCE.colorKey,
+            backgroundColor: appearance.backgroundColor,
+            accentColor: appearance.accentColor,
+        });
+        const exteriorColor = appearance.glowColor?.startsWith('#') ? appearance.glowColor : appearance.accentColor;
+        const interiorColor = resolveInnerBorderColor(appearance.innerBorderColor);
+        waveform?.stop();
+        waveform = null;
+        wrapper.replaceChildren();
+        const { root, fill: fillNode } = buildDoubleBorder({
+            fillDiameter: size,
+            borderRadius: size,
+            exteriorColor,
+            exteriorWidthSlider: appearance.glowIntensity ?? DEFAULT_ORB_APPEARANCE.glowIntensity,
+            interiorColor,
+            interiorWidthSlider: appearance.innerBorderWidth,
+            fill,
+        });
+        fillEl = fillNode;
+        wrapper.appendChild(root);
+        renderContent();
+    }
+    function renderContent() {
+        if (!fillEl)
+            return;
+        const size = appearance.size ?? DEFAULT_ORB_APPEARANCE.size;
+        const waveColor = appearance.waveformColor ?? '#ffffff';
+        waveform?.stop();
+        waveform = null;
+        fillEl.replaceChildren();
+        wrapper.style.animation = state === 'speaking' ? 'fy-opulse 1.1s ease-in-out infinite' : '';
+        if (state === 'thinking') {
+            fillEl.appendChild(buildThinkingSpinner(size, waveColor));
+            return;
+        }
+        if (state === 'listening') {
+            waveform = buildWaveform(waveColor, Math.round(size * 0.46));
+            waveform.setVolume(volume);
+            fillEl.appendChild(waveform.el);
+            waveform.start();
+            return;
+        }
+        if (appearance.logoDataUrl) {
+            const img = document.createElement('img');
+            img.src = appearance.logoDataUrl;
+            img.alt = '';
+            img.draggable = false;
+            img.addEventListener('dragstart', (e) => e.preventDefault());
+            Object.assign(img.style, {
+                width: '64%',
+                height: '64%',
+                objectFit: 'contain',
+                // The orb moves as a whole via the button's pointer drag — never let the
+                // browser grab/select the PNG itself.
+                pointerEvents: 'none',
+                userSelect: 'none',
+                webkitUserSelect: 'none',
+                webkitUserDrag: 'none',
+            });
+            fillEl.appendChild(img);
+            return;
+        }
+        if (state === 'idle') {
+            fillEl.appendChild(buildOrbMark(size));
+        }
+    }
+    rebuild();
+    return {
+        element: wrapper,
+        applyAppearance(next) {
+            appearance = next;
+            rebuild();
+        },
+        applyState(nextState, nextVolume) {
+            volume = nextVolume;
+            if (nextState !== state) {
+                state = nextState;
+                renderContent();
+            }
+            else if (state === 'listening') {
+                waveform?.setVolume(volume);
+            }
+        },
+    };
+}

package/dist/esm/orb/publishedConfig.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Published orb config watcher — framework-free.
+ *
+ * The vanilla web equivalent of @fiodos/react-native's usePublishedOrbConfig and
+ * @fiodos/react's usePublishedOrbConfig hook. Fetches the dashboard-published orb
+ * config (GET /v1/client/config via the controller's backend client) and maps it
+ * with the SAME @fiodos/core mapper (mapPublishedConfigToOrbProps), so color /
+ * size / glow / logo / keyboard-chip / screen position apply on web exactly as on
+ * mobile — in real time, via polling. So Vue/Svelte/Angular read the dashboard
+ * config identically to the reference, instead of ignoring it.
+ */
+import { type OrbScreenPosition, type PublishedModalTheme } from '@fiodos/core';
+import type { AgentController } from '../controller/AgentController.js';
+import { type ChipTheme, type OrbAppearance } from './orbView.js';
+export interface ResolvedOrbConfig {
+    appearance: OrbAppearance;
+    keyboardChip: ChipTheme | null;
+    modalTheme: PublishedModalTheme | undefined;
+    screenPosition: OrbScreenPosition | undefined;
+}
+export interface WatchPublishedConfigOptions {
+    /** Poll interval (ms) to pick up dashboard changes in real time. Default 12000. */
+    pollMs?: number;
+    /** Called with the resolved config (or null when nothing is published). */
+    onChange: (config: ResolvedOrbConfig | null) => void;
+}
+/**
+ * Starts watching the published config. Returns an unsubscribe function.
+ * Best-effort: a failed fetch reports `null` (the orb keeps its current/default
+ * look) and never throws into the host app.
+ */
+export declare function watchPublishedConfig(controller: AgentController, options: WatchPublishedConfigOptions): () => void;

package/dist/esm/orb/publishedConfig.js

@@ -0,0 +1,67 @@
+/**
+ * Published orb config watcher — framework-free.
+ *
+ * The vanilla web equivalent of @fiodos/react-native's usePublishedOrbConfig and
+ * @fiodos/react's usePublishedOrbConfig hook. Fetches the dashboard-published orb
+ * config (GET /v1/client/config via the controller's backend client) and maps it
+ * with the SAME @fiodos/core mapper (mapPublishedConfigToOrbProps), so color /
+ * size / glow / logo / keyboard-chip / screen position apply on web exactly as on
+ * mobile — in real time, via polling. So Vue/Svelte/Angular read the dashboard
+ * config identically to the reference, instead of ignoring it.
+ */
+import { mapPublishedConfigToOrbProps, } from '@fiodos/core';
+import { DEFAULT_ORB_APPEARANCE } from './orbView.js';
+function toResolved(props) {
+    const theme = props.theme;
+    const appearance = {
+        accentColor: theme.accentColor ?? DEFAULT_ORB_APPEARANCE.accentColor,
+        backgroundColor: theme.backgroundColor ?? DEFAULT_ORB_APPEARANCE.backgroundColor,
+        glowColor: theme.glowColor,
+        colorKey: theme.colorKey,
+        glowIntensity: theme.glowIntensity,
+        innerBorderColor: theme.innerBorderColor,
+        innerBorderWidth: theme.innerBorderWidth,
+        size: theme.size ?? DEFAULT_ORB_APPEARANCE.size,
+        waveformColor: theme.waveformColor,
+        logoDataUrl: props.logoDataUrl,
+    };
+    return {
+        appearance,
+        keyboardChip: theme.keyboardChip ?? null,
+        modalTheme: props.modalTheme,
+        screenPosition: props.screenPosition,
+    };
+}
+/**
+ * Starts watching the published config. Returns an unsubscribe function.
+ * Best-effort: a failed fetch reports `null` (the orb keeps its current/default
+ * look) and never throws into the host app.
+ */
+export function watchPublishedConfig(controller, options) {
+    const fetcher = controller.config.backend.fetchPublishedConfig;
+    if (!fetcher) {
+        options.onChange(null);
+        return () => { };
+    }
+    let cancelled = false;
+    const load = async () => {
+        try {
+            const res = await fetcher.call(controller.config.backend);
+            if (cancelled)
+                return;
+            options.onChange(res.published ? toResolved(mapPublishedConfigToOrbProps(res.published)) : null);
+        }
+        catch {
+            if (!cancelled)
+                options.onChange(null);
+        }
+    };
+    void load();
+    const pollMs = options.pollMs ?? 12000;
+    const timer = pollMs > 0 ? setInterval(() => void load(), pollMs) : null;
+    return () => {
+        cancelled = true;
+        if (timer)
+            clearInterval(timer);
+    };
+}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/speech/speechSession.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Framework-free speech session — wraps a @fiodos/core VoiceAdapter's
+ * recognition into the state machine the orchestrator depends on:
+ *
+ *   idle → recording → transcribing → (transcript | nothing) → idle
+ *
+ * This is the vanilla equivalent of @fiodos/react's `useSpeechSession` hook:
+ * the same state machine, exposed via a `subscribe` listener instead of React
+ * state, so it drives any framework.
+ */
+import type { VoiceAdapter } from '@fiodos/core';
+export type SpeechSessionState = 'idle' | 'recording' | 'transcribing';
+export interface SpeechSessionSnapshot {
+    state: SpeechSessionState;
+    interimText: string;
+    volumeLevel: number;
+}
+export interface SpeechSessionOptions {
+    adapter: VoiceAdapter;
+    /** STT locale — always explicit, from the SDK config. */
+    locale: string;
+    maxSeconds: number;
+    onTranscript: (text: string) => void;
+    /** Recognition error (permission denied, native failure, unavailable). */
+    onError?: (error: unknown) => void;
+}
+export interface SpeechSession {
+    getSnapshot(): SpeechSessionSnapshot;
+    subscribe(listener: (snapshot: SpeechSessionSnapshot) => void): () => void;
+    start(): Promise<void>;
+    stop(): void;
+    cancel(): void;
+    dispose(): void;
+}
+export declare function createSpeechSession(options: SpeechSessionOptions): SpeechSession;

package/dist/esm/speech/speechSession.js

@@ -0,0 +1,57 @@
+export function createSpeechSession(options) {
+    const { adapter, locale, maxSeconds } = options;
+    let snapshot = { state: 'idle', interimText: '', volumeLevel: 0 };
+    const listeners = new Set();
+    function emit(next) {
+        snapshot = { ...snapshot, ...next };
+        for (const l of listeners)
+            l(snapshot);
+    }
+    function resetToIdle() {
+        emit({ state: 'idle', interimText: '', volumeLevel: 0 });
+    }
+    return {
+        getSnapshot() {
+            return snapshot;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        async start() {
+            if (snapshot.state !== 'idle')
+                return;
+            emit({ state: 'recording', interimText: '', volumeLevel: 0.85 });
+            await adapter.startListening({ locale, continuous: true, maxSeconds }, {
+                onInterim: (text) => emit({ interimText: text }),
+                onFinal: (text) => {
+                    resetToIdle();
+                    if (text.trim())
+                        options.onTranscript(text);
+                },
+                onEnd: () => {
+                    if (snapshot.state !== 'idle')
+                        resetToIdle();
+                },
+                onError: (error) => {
+                    resetToIdle();
+                    options.onError?.(error);
+                },
+            });
+        },
+        stop() {
+            if (snapshot.state !== 'recording')
+                return;
+            emit({ state: 'transcribing', volumeLevel: 0 });
+            adapter.stopListening();
+        },
+        cancel() {
+            adapter.cancelListening();
+            resetToIdle();
+        },
+        dispose() {
+            adapter.cancelListening();
+            listeners.clear();
+        },
+    };
+}