dsh-compact-saviour 0.2.6

package/src/client/index.tsx

@@ -0,0 +1,214 @@
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client';
+import type { Context } from '@deepseek-ai/cordis';
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client';
+import type {} from '@deepseek-ai/dsh-client-ui-slots';
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import type { Config, ModelOption, State } from '../shared.js';
+import { MeterBridge } from './meter-bridge.js';
+import { RingControl } from './ring-control.js';
+import { WaitingCopy } from './waiting-copy.js';
+import { contextRoot, contextRing, contextPanel } from './context-elements.js';
+import './style.css';
+
+export const name = 'dsh-compact-saviour-client';
+export const inject = ['slots'];
+const ENDPOINT = '/api/dsh-compact-saviour/v1';
+async function api<T>(params = '', data?: unknown, signal?: AbortSignal): Promise<T> {
+  const response = await fetch(ENDPOINT + params, { credentials: 'same-origin', signal,
+    ...(data ? { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(data) } : {}),
+  });
+  const text = await response.text();
+  let value;
+  try { value = JSON.parse(text); }
+  catch { throw new Error(`压缩服务暂未就绪（HTTP ${response.status}），请稍后重试。`); }
+  if (!response.ok) throw new Error(value.error ?? `HTTP ${response.status}`);
+  return value;
+}
+
+/** A zero-layout anchor scopes the native ring gesture, status animation and popup. */
+export function PopupBridge({ sessionId }: { sessionId: string }) {
+  const anchor = useRef<HTMLSpanElement>(null);
+  const [footer, setFooter] = useState<HTMLDivElement | null>(null);
+  const [state, setState] = useState<State>();
+  const [error, setError] = useState('');
+  const [sending, setSending] = useState(false);
+  const posting = useRef(false);
+  const act = useRef<(action: string) => Promise<void>>(async () => {});
+  const latest = useRef<State>();
+  const syncMeter = useRef<() => void>(() => {});
+  useEffect(() => {
+    const abort = new AbortController(); let timer: ReturnType<typeof setTimeout>;
+    let revision = 0, connectionError = '';
+    setState(undefined); latest.current = undefined; setError(''); setSending(false); posting.current = false;
+    const update = (value: State) => { latest.current = value; setState(value); syncMeter.current(); };
+    act.current = async (action: string) => {
+      if (posting.current || abort.signal.aborted) return;
+      posting.current = true; revision++; setSending(true); setError(''); syncMeter.current();
+      try {
+        const value = await api<State>('', { action, sessionId }, abort.signal);
+        // POST acknowledges a job without remeasuring context. Keep the last
+        // same-session reading until GET replaces it, avoiding an 8M flash.
+        if (!abort.signal.aborted) update({ ...value, context: value.context ?? latest.current?.context });
+      } catch (e) {
+        if (!abort.signal.aborted) setError(e instanceof Error ? e.message : String(e));
+      } finally {
+        if (!abort.signal.aborted) { posting.current = false; revision++; setSending(false); syncMeter.current(); }
+      }
+    };
+    const poll = async () => {
+      const started = revision;
+      try {
+        const value = await api<State>(`?sessionId=${encodeURIComponent(sessionId)}`, undefined, abort.signal);
+        if (!abort.signal.aborted && started === revision && !posting.current) {
+          update(value); const previous = connectionError;
+          setError(current => current === previous ? '' : current); connectionError = '';
+        }
+      } catch (e) {
+        if (!abort.signal.aborted) { connectionError = e instanceof Error ? e.message : String(e); setError(connectionError); }
+      }
+      if (!abort.signal.aborted) timer = setTimeout(poll, 1000);
+    };
+    void poll(); return () => { abort.abort(); clearTimeout(timer); act.current = async () => {}; };
+  }, [sessionId]);
+  useEffect(() => {
+    const root = anchor.current && contextRoot(anchor.current);
+    if (!root) return;
+    let owned: HTMLDivElement | null = null;
+    let observedPanel: HTMLElement | undefined;
+    const meter = new MeterBridge();
+    let control: RingControl | undefined;
+    const sync = () => {
+      const ring = contextRing(root);
+      const panel = contextPanel(ring);
+      if (panel !== observedPanel) {
+        panelObserver.disconnect(); observedPanel = panel;
+        if (panel) panelObserver.observe(panel, observeOptions);
+      }
+      meter.apply(ring, latest.current?.context);
+      if (control?.button !== ring) {
+        control?.destroy(); control = ring ? new RingControl(ring, () => { void act.current('configured'); }) : undefined;
+      }
+      control?.update(posting.current ? 'sending' : latest.current?.job.phase ?? 'idle', Boolean(latest.current?.available));
+      if (owned && owned.parentElement === panel) {
+        // The optional breakdown can arrive after the portal footer. React
+        // appends its new rows last; keep our action beneath those native rows.
+        if (panel && panel.lastElementChild !== owned) panel.append(owned);
+        return;
+      }
+      owned?.remove(); owned = null;
+      if (panel && !panel.querySelector('[data-compact-saviour]')) {
+        owned = document.createElement('div'); owned.dataset.compactSaviour = 'footer'; owned.className = 'dsh-cs-footer'; panel.append(owned);
+      }
+      setFooter(owned);
+    };
+    const observeOptions = { childList: true, subtree: true, characterData: true, attributes: true, attributeFilter: ['aria-expanded', 'aria-label', 'aria-describedby', 'stroke-dasharray', 'style'] };
+    const observer = new MutationObserver(sync);
+    const panelObserver = new MutationObserver(sync);
+    const portals = new MutationObserver(sync);
+    observer.observe(root, observeOptions);
+    // Only direct body children, not the streaming transcript subtree.
+    portals.observe(root.ownerDocument.body, { childList: true });
+    syncMeter.current = sync; sync();
+    return () => { syncMeter.current = () => {}; observer.disconnect(); portals.disconnect(); panelObserver.disconnect(); control?.destroy(); meter.restore(); owned?.remove(); };
+  }, [sessionId]);
+  return <><span ref={anchor} style={{ display: 'none' }} aria-hidden="true" />{footer && createPortal(<CompactFooter state={state} sending={sending} error={error} act={action => act.current(action)} />, footer)}</>;
+}
+
+function CompactFooter({ state, sending, error, act }: {
+  state?: State; sending: boolean; error: string; act(action: string): Promise<void>;
+}) {
+  const job = state?.job, active = job?.phase === 'queued' || job?.phase === 'running';
+  const current = job?.current;
+  const busy = sending || active;
+  const running = !sending && job?.phase === 'running';
+  const stage = job?.message.includes('合并摘要') ? 'merge' : 'compress';
+  const label = sending ? '正在提交' : job?.phase === 'queued' ? '等待当前步骤结束' : job?.phase === 'running'
+    ? stage === 'merge' ? '正在合并摘要' : '正在压缩' : '手动压缩';
+  const progress = !sending && job?.phase === 'running' && Number.isInteger(job.completed) && Number.isInteger(job.total)
+    && job.total! > 1 && job.completed! >= 0 && job.completed! <= job.total! ? `${job.completed}/${job.total}` : '';
+  return <div className="dsh-cs-content" data-phase={sending ? 'sending' : job?.phase ?? 'idle'}>
+    <button className="dsh-cs-button dsh-cs-primary dsh-cs-compact" type="button" aria-label={progress ? `${label} ${progress}` : label} disabled={sending || !state?.available || active} onClick={() => void act('configured')}>
+      <span className="dsh-cs-button-status" aria-hidden="true">
+        {running ? <WaitingCopy key={stage} stage={stage} /> : <span className="dsh-cs-label">{label}{busy ? '…' : ''}</span>}
+        {progress && <span className="dsh-cs-progress"> {progress}</span>}
+      </span>
+      <span className="dsh-cs-sr-status" role="status" aria-live="polite" aria-atomic="true">{label}{progress ? ` ${progress}` : ''}</span>
+    </button>
+    {!active && !sending && <div className="dsh-cs-hint">也可以长按圆环直接压缩</div>}
+    {!busy && job?.message && <div className="dsh-cs-status dsh-cs-job-status" role="status"><span>{job.message}{job.phase === 'done' && job.beforeTokens !== undefined && job.afterTokens !== undefined ? ` ${Math.round(job.beforeTokens / 1000)}K → ${Math.round(job.afterTokens / 1000)}K` : ''}</span></div>}
+    {state?.context?.corrected && <div className="dsh-cs-status">{state.context.reason === 'invalid-usage' ? '已排除异常历史用量，当前按消息和工具估算。' : '已按新模型的上下文容量重新估算。'}</div>}
+    {error && <div className="dsh-cs-error" role="alert">{error}</div>}
+    {state && !state.config.model && !error && <div className="dsh-cs-status">先在设置 → Compact Saviour 中选择压缩模型。</div>}
+    {state && !state.available && <div className="dsh-cs-status">当前会话的 Compact 后端尚未就绪。</div>}
+    {job?.phase === 'failed' && <div className="dsh-cs-actions">
+      <button className="dsh-cs-button" disabled={sending} onClick={() => void act('configured')}>重试压缩模型</button>
+      {current && <button className="dsh-cs-button" disabled={sending} onClick={() => void act('current')}>本次使用 {current.model} · {current.reasoningEffort || '默认推理'}</button>}
+    </div>}
+    {(active || job?.phase === 'failed') && <button className="dsh-cs-button" disabled={sending} onClick={() => void act('cancel')}>取消</button>}
+  </div>;
+}
+
+function SettingsPanel() {
+  const [config, setConfig] = useState<Config>();
+  const [models, setModels] = useState<ModelOption[]>([]);
+  const [search, setSearch] = useState('');
+  const [efforts, setEfforts] = useState<{ id: string; name: string }[]>([]);
+  const [message, setMessage] = useState('');
+  const [saving, setSaving] = useState(false);
+  useEffect(() => {
+    const abort = new AbortController();
+    void Promise.all([api<State>('', undefined, abort.signal), api<{ models: ModelOption[] }>('?models=1', undefined, abort.signal)])
+      .then(([s, m]) => { setConfig(s.config); setModels(m.models); })
+      .catch(e => { if (!abort.signal.aborted) setMessage(e.message); });
+    return () => abort.abort();
+  }, []);
+  useEffect(() => {
+    const abort = new AbortController(); setEfforts([]);
+    if (config?.provider && config.model) void api<{ efforts: { id: string; name: string }[] }>(`?provider=${encodeURIComponent(config.provider)}&model=${encodeURIComponent(config.model)}`, undefined, abort.signal)
+      .then(v => setEfforts(v.efforts)).catch(e => { if (!abort.signal.aborted) setMessage(e.message); });
+    return () => abort.abort();
+  }, [config?.provider, config?.model]);
+  const save = async () => {
+    setSaving(true); setMessage('');
+    try { const s = await api<State>('', { action: 'settings', config }); setConfig(s.config); setMessage('已保存。'); }
+    catch (e) { setMessage(e instanceof Error ? e.message : String(e)); }
+    finally { setSaving(false); }
+  };
+  const selected = config?.model ? JSON.stringify([config.provider, config.model]) : '';
+  const filtered = models.filter(m => JSON.stringify([m.provider, m.id]) === selected || `${m.name} ${m.id} ${m.provider}`.toLowerCase().includes(search.toLowerCase()));
+  return <section className="dsh-cs-settings">
+    <h2>Compact Saviour</h2>
+    <p>独立模型负责上下文压缩。点击圆环查看用量，长按圆环或点击弹层内的按钮开始压缩。</p>
+    {config ? <>
+      <label className="dsh-cs-toggle"><input type="checkbox" checked={config.enabled} onChange={e => setConfig({ ...config, enabled: e.target.checked })} /> 启用自动压缩辅助</label>
+      <label>自动压缩方式<select value={config.mode ?? 'rescue'} disabled={!config.enabled} onChange={e => setConfig({ ...config, mode: e.target.value as 'direct' | 'rescue' })}>
+        <option value="rescue">官方连续失败两次后救援（默认）</option>
+        <option value="direct">直接使用 Saviour 模型</option>
+      </select></label>
+      <p>{!config.enabled ? '自动压缩由官方处理。手动压缩仍直接使用下方模型。' : config.mode === 'direct' ? '自动和手动压缩都直接使用下方模型。' : '自动压缩先由官方处理，连续失败两次后静默救援。手动压缩直接使用下方模型。'}</p>
+      <label>Saviour 压缩模型<input placeholder="搜索已配置的模型" value={search} onChange={e => setSearch(e.target.value)} /></label>
+      <select aria-label="压缩模型" value={selected} onChange={e => { const [provider, model] = e.target.value ? JSON.parse(e.target.value) : ['', '']; setConfig({ ...config, provider, model, reasoningEffort: '' }); }}>
+        <option value="">请选择模型</option>
+        {filtered.map(m => <option key={JSON.stringify([m.provider, m.id])} value={JSON.stringify([m.provider, m.id])}>{m.name} · {m.provider}</option>)}
+      </select>
+      <label>Reasoning level<select value={config.reasoningEffort} onChange={e => setConfig({ ...config, reasoningEffort: e.target.value })}>
+        <option value="">模型默认</option>{efforts.map(e => <option key={e.id} value={e.id}>{e.name}</option>)}
+      </select></label>
+      <p>超长历史自动分块，保留近期消息和原始记录。失败后由你选择重试、仅本次使用当前对话模型，或取消。</p>
+      <button className="dsh-cs-button dsh-cs-primary" disabled={saving} onClick={() => void save()}>{saving ? '保存中…' : '保存'}</button>
+    </> : <p>正在加载模型配置…</p>}
+    {message && <p role="status">{message}</p>}
+  </section>;
+}
+
+export function apply(ctx: Context): void {
+  ctx.slots.inject('conversation.input.right', () => ctx.slots.register({
+    name: 'conversation.input.right', id: 'compact-saviour-popup-anchor', order: 100,
+    inject: (sessionId: string) => ({ sessionId }),
+  }, PopupBridge));
+  ctx.slots.inject('settings.section', () => ctx.slots.register({
+    name: 'settings.section', id: 'compact-saviour', order: 38, label: () => 'Compact Saviour',
+  }, SettingsPanel));
+}

package/src/client/meter-bridge.ts

@@ -0,0 +1,65 @@
+import type { ContextView } from '../shared.js';
+import { contextPanel } from './context-elements.js';
+
+function tokens(value: number): string {
+  const unit = value >= 1_000_000 ? 1_000_000 : value >= 1_000 ? 1_000 : 1;
+  const scaled = value / unit;
+  return `${scaled >= 100 || unit === 1 ? Math.round(scaled) : Math.round(scaled * 10) / 10}${unit === 1_000_000 ? 'M' : unit === 1_000 ? 'K' : ''}`;
+}
+type Owned = { read(): string | null; write(value: string | null): void; before: string | null; last: string | null; desired?: string };
+
+/** Narrow compatibility bridge until DSH exposes a context-meter reading slot.
+ * Preserve the original React nodes, styles, handlers and any later owner update. */
+export class MeterBridge {
+  private edits = new Map<Node, Map<string, Owned>>();
+  private write(node: Node, key: string, value: string, read: Owned['read'], write: Owned['write']) {
+    let fields = this.edits.get(node);
+    if (!fields) { fields = new Map(); this.edits.set(node, fields); }
+    let field = fields.get(key);
+    if (!field) { field = { read, write, before: read(), last: null }; fields.set(key, field); }
+    else if (read() !== field.last) field.before = read();
+    if (read() !== value && !(field.desired === value && read() === field.last)) write(value);
+    field.last = read(); field.desired = value;
+  }
+  private text(element: Element | null | undefined, value: string) {
+    const node = element?.firstChild;
+    if (element?.childNodes.length !== 1 || node?.nodeType !== Node.TEXT_NODE) return;
+    this.write(node, 'text', value, () => node.nodeValue, v => { node.nodeValue = v; });
+  }
+  private attr(element: Element, key: string, value: string) {
+    this.write(element, key, value, () => element.getAttribute(key), v => { if (v === null) element.removeAttribute(key); else element.setAttribute(key, v); });
+  }
+  restore() {
+    for (const fields of this.edits.values()) for (const edit of fields.values()) if (edit.read() === edit.last) edit.write(edit.before);
+    this.edits.clear();
+  }
+  apply(ring: HTMLButtonElement | undefined, context?: ContextView) {
+    if (!ring || !context?.corrected) { this.restore(); return; }
+    for (const node of this.edits.keys()) if (!node.isConnected) this.edits.delete(node);
+    const percent = Math.max(0, Math.min(100, Math.round(context.usedTokens / context.contextWindow * 100)));
+    const reading = `${percent}%`, circumference = 2 * Math.PI * 5.5;
+    // RC2 displays a percentage alongside the SVG in the dock.
+    const label = [...ring.children].find(child => child.tagName === 'SPAN' && /^\d+%$/.test(child.textContent ?? ''));
+    this.text(label, reading);
+    const circles = ring.querySelectorAll('svg[viewBox="0 0 14 14"] circle');
+    if (circles.length !== 2) { this.restore(); return; }
+    this.attr(circles[1]!, 'stroke-dasharray', `${circumference * percent / 100} ${circumference}`);
+    const aria = ring.getAttribute('aria-label');
+    if (aria && /\d+%/.test(aria)) this.attr(ring, 'aria-label', aria.replace(/\d+%/, reading));
+    const tooltipId = ring.getAttribute('aria-describedby');
+    const tooltip = tooltipId ? document.getElementById(tooltipId) : null;
+    if (tooltip?.getAttribute('role') === 'tooltip') this.text(tooltip, (tooltip.textContent ?? '').replace(/\d+%/, reading));
+    const panel = contextPanel(ring);
+    const header = panel?.firstElementChild, bar = header?.nextElementSibling;
+    if (!header || header.children.length !== 4 || !bar || !/^\d+%$/.test(header.children[1]?.textContent ?? '')) return;
+    this.text(header.children[1], reading);
+    this.text(header.children[3], `~${tokens(context.usedTokens)} / ${tokens(context.contextWindow)}`);
+    const parts = context.parts?.filter(value => value > 0), total = parts?.reduce((a, b) => a + b, 0);
+    if (parts && total && parts.length === bar.children.length) {
+      [...bar.children].forEach((segment, index) => {
+        const el = segment as HTMLElement;
+        this.write(el, 'width', `${percent * parts[index]! / total}%`, () => el.style.width, value => { el.style.width = value ?? ''; });
+      });
+    }
+  }
+}

package/src/client/ring-control.ts

@@ -0,0 +1,134 @@
+import { Satellite } from './satellite.js';
+
+export const HOLD_MS = 650;
+export type RingPhase = 'idle' | 'sending' | 'queued' | 'running' | 'done' | 'failed';
+/** Enhance only the existing context button; native short click and keys survive. */
+export class RingControl {
+  private host = document.createElement('span');
+  private bot: Satellite;
+  private timer?: ReturnType<typeof setTimeout>;
+  private pointer?: { id: number; x: number; y: number };
+  private suppressedUntil = 0;
+  private phase: RingPhase = 'idle';
+  private available = false;
+  private disposed = false;
+  private previousTitle: string | null;
+  private lastTitle = '';
+  private native?: { element: SVGElement; fields: Map<string, { before: string; priority: string; last: string; lastPriority: string }> };
+  constructor(readonly button: HTMLButtonElement, private activate: () => void) {
+    this.previousTitle = button.getAttribute('title');
+    this.host.className = 'dsh-cs-ring-art'; this.host.setAttribute('aria-hidden', 'true');
+    this.host.innerHTML = '<svg class="dsh-cs-hold" viewBox="0 0 32 32"><circle cx="16" cy="16" r="14" pathLength="1"/></svg>';
+    this.bot = new Satellite(this.host); button.append(this.host); button.classList.add('dsh-cs-ring');
+    button.addEventListener('pointerdown', this.down);
+    button.addEventListener('pointerleave', this.cancel);
+    button.addEventListener('pointercancel', this.cancel);
+    button.addEventListener('contextmenu', this.context);
+    button.addEventListener('click', this.click, true);
+    window.addEventListener('pointerup', this.up, true);
+    window.addEventListener('pointermove', this.move, true);
+    window.addEventListener('pointerdown', this.anotherPointer, true);
+    window.addEventListener('blur', this.cancel);
+    document.addEventListener('visibilitychange', this.cancel);
+  }
+  update(phase: RingPhase, available: boolean) {
+    this.available = available;
+    // Restore the native meter from job state, never from an animation callback.
+    // React may also replace the trigger's class while updating its usage label.
+    this.button.classList.add('dsh-cs-ring');
+    if (this.host.parentElement !== this.button) this.button.append(this.host);
+    if (this.button.dataset.csPhase !== phase) this.button.dataset.csPhase = phase;
+    this.showMeter(!['sending', 'queued', 'running'].includes(phase));
+    if (this.phase !== phase) {
+      this.phase = phase;
+      if (phase === 'running') { this.button.dataset.csMotion = 'running'; this.bot.setRunning(true); }
+      else if (phase === 'queued' || phase === 'sending') { this.button.dataset.csMotion = 'queued'; this.bot.setRunning(false); }
+      else {
+        this.button.dataset.csMotion = 'settling';
+        this.bot.setRunning(false, () => { if (!this.disposed) delete this.button.dataset.csMotion; });
+      }
+    }
+    const title = phase === 'running' ? '正在压缩上下文 · 点击查看进度'
+      : phase === 'queued' || phase === 'sending' ? '压缩已排队 · 点击查看进度'
+      : '点击查看上下文 · 长按压缩';
+    if (this.button.title !== title) this.button.title = title;
+    this.lastTitle = title;
+    if (!this.canHold()) this.cancel();
+  }
+  private restoreMeter() {
+    if (!this.native) return;
+    for (const [key, field] of this.native.fields) {
+      if (this.native.element.style.getPropertyValue(key) !== field.last || this.native.element.style.getPropertyPriority(key) !== field.lastPriority) continue;
+      if (field.before) this.native.element.style.setProperty(key, field.before, field.priority);
+      else this.native.element.style.removeProperty(key);
+    }
+    this.native = undefined;
+  }
+  private showMeter(visible: boolean) {
+    const element = this.button.querySelector<SVGElement>('svg[viewBox="0 0 14 14"]');
+    if (this.native?.element !== element) {
+      this.restoreMeter();
+      if (element) this.native = { element, fields: new Map() };
+    }
+    if (!this.native) return;
+    // The RC2 trigger includes percentage text. Keep the animation over the
+    // actual icon instead of stretching it across the whole button.
+    const iconBox = this.native.element.getBoundingClientRect(), buttonBox = this.button.getBoundingClientRect();
+    const position = { left: `${iconBox.left - buttonBox.left - 3}px`, top: `${iconBox.top - buttonBox.top - 3}px`, width: `${iconBox.width + 6}px`, height: `${iconBox.height + 6}px` };
+    for (const [key, value] of Object.entries(position)) if (this.host.style.getPropertyValue(key) !== value) this.host.style.setProperty(key, value);
+    // Set the SVG itself: ancestor-attribute selector invalidation can leave an
+    // SVG's computed visibility/opacity stale even when the job is already idle.
+    for (const [key, value] of [['visibility', 'visible'], ['opacity', visible ? '1' : '0']] as const) {
+      const style = this.native.element.style;
+      let field = this.native.fields.get(key);
+      if (!field || style.getPropertyValue(key) !== field.last || style.getPropertyPriority(key) !== field.lastPriority) {
+        field = { before: style.getPropertyValue(key), priority: style.getPropertyPriority(key), last: value, lastPriority: '' };
+        this.native.fields.set(key, field);
+      }
+      if (style.getPropertyValue(key) !== value) style.setProperty(key, value);
+      field.last = value; field.lastPriority = style.getPropertyPriority(key);
+    }
+  }
+  private canHold() { return this.available && !['sending', 'queued', 'running'].includes(this.phase); }
+  private down = (event: PointerEvent) => {
+    this.suppressedUntil = 0;
+    if (!event.isPrimary || event.button !== 0 || !this.canHold()) return;
+    this.cancel(); this.pointer = { id: event.pointerId, x: event.clientX, y: event.clientY };
+    this.button.dataset.csHolding = 'true';
+    this.timer = setTimeout(() => {
+      if (!this.pointer || !this.canHold() || !this.button.isConnected) { this.cancel(); return; }
+      this.cancel(); this.suppressedUntil = Infinity;
+      // Synthetic keyboard-style click is deliberately allowed; open the native
+      // popup once so model/configuration errors always have a visible home.
+      if (this.button.getAttribute('aria-expanded') !== 'true') this.button.click();
+      this.activate();
+    }, HOLD_MS);
+  };
+  private anotherPointer = (event: PointerEvent) => { if (this.pointer && this.pointer.id !== event.pointerId) this.cancel(); };
+  private move = (event: PointerEvent) => { if (this.pointer?.id === event.pointerId && Math.hypot(event.clientX - this.pointer.x, event.clientY - this.pointer.y) > 10) this.cancel(); };
+  private up = (event: PointerEvent) => {
+    if (this.pointer?.id === event.pointerId) this.cancel();
+    if (this.suppressedUntil === Infinity) this.suppressedUntil = performance.now() + 700;
+  };
+  private context = (event: Event) => { if (this.pointer || performance.now() < this.suppressedUntil) event.preventDefault(); };
+  private click = (event: MouseEvent) => {
+    if (event.detail !== 0 && performance.now() < this.suppressedUntil) { event.preventDefault(); event.stopImmediatePropagation(); }
+  };
+  private cancel = () => {
+    clearTimeout(this.timer); this.timer = undefined; this.pointer = undefined; delete this.button.dataset.csHolding;
+  };
+  destroy() {
+    this.disposed = true; this.cancel(); this.bot.destroy(); this.host.remove();
+    this.button.classList.remove('dsh-cs-ring'); delete this.button.dataset.csMotion; delete this.button.dataset.csPhase;
+    this.restoreMeter();
+    if (this.button.title === this.lastTitle) {
+      if (this.previousTitle === null) this.button.removeAttribute('title'); else this.button.title = this.previousTitle;
+    }
+    this.button.removeEventListener('pointerdown', this.down); this.button.removeEventListener('pointerleave', this.cancel);
+    this.button.removeEventListener('pointercancel', this.cancel); this.button.removeEventListener('contextmenu', this.context);
+    this.button.removeEventListener('click', this.click, true);
+    window.removeEventListener('pointerup', this.up, true); window.removeEventListener('pointermove', this.move, true);
+    window.removeEventListener('pointerdown', this.anotherPointer, true); window.removeEventListener('blur', this.cancel);
+    document.removeEventListener('visibilitychange', this.cancel);
+  }
+}

package/src/client/satellite.ts

@@ -0,0 +1,121 @@
+import motion from './vendor/open-bot-motion.cjs';
+
+const NS = 'http://www.w3.org/2000/svg';
+let nextClip = 0;
+const clipPrefix = Math.random().toString(36).slice(2);
+const element = (tag: string) => document.createElementNS(NS, tag);
+type Frame = ReturnType<typeof motion.getBot7State>;
+// The authored orbit has a 3.6 s period. Loop just that span, not the complete
+// demo (whose final satellite frame does not match its initial resting pose).
+export const orbitTime = (seconds: number) => seconds < .8 ? 2 + seconds : 2.8 + ((seconds - .8) % 3.6);
+export function settleFrame(from: Frame, amount: number): Frame {
+  const idle = motion.getBot7State(0), bot = { ...idle.bot };
+  const t = 1 - (1 - amount) ** 3;
+  for (const key of Object.keys(bot)) if (typeof bot[key] === 'number' && typeof from.bot[key] === 'number') {
+    bot[key] = (from.bot[key] as number) * (1 - t) + (bot[key] as number) * t;
+  }
+  return { bot, dots: from.dots.map(dot => ({ ...dot, x: dot.x * (1 - t), y: dot.y * (1 - t), r: dot.r * (1 - t) })) };
+}
+
+/** Owns one SVG and one clock. Hidden/reduced-motion pages consume no frames. */
+export class Satellite {
+  readonly svg = element('svg');
+  private projector = new motion.SvgProjector({ viewportSize: 280 });
+  private body = element('path');
+  private clipBody = element('path');
+  private eyes = element('g');
+  private dots = Array.from({ length: 8 }, () => element('circle'));
+  private frame?: number;
+  private elapsed = 0;
+  private lastTime = 0;
+  private settling = 0;
+  private mode: 'rest' | 'run' | 'settle' = 'rest';
+  private current = motion.getBot7State(0);
+  private exitFrom = this.current;
+  private reduced = matchMedia('(prefers-reduced-motion: reduce)');
+  private disposed = false;
+  private done?: () => void;
+  constructor(host: HTMLElement) {
+    this.svg.setAttribute('viewBox', '-76 -76 152 152');
+    this.svg.setAttribute('aria-hidden', 'true');
+    this.svg.classList.add('dsh-cs-robot');
+    const defs = element('defs'), clip = element('clipPath');
+    // SVG clip identity is not a credential; also work on non-secure HTTP pages.
+    const id = `dsh-cs-bot-${clipPrefix}-${nextClip++}`;
+    clip.id = id; clip.append(this.clipBody); defs.append(clip);
+    this.eyes.setAttribute('clip-path', `url(#${id})`);
+    this.body.classList.add('dsh-cs-body'); this.eyes.classList.add('dsh-cs-eyes');
+    this.dots.forEach(dot => dot.classList.add('dsh-cs-dot'));
+    this.svg.append(defs, this.body, this.eyes, ...this.dots); host.append(this.svg);
+    this.render(this.current);
+    document.addEventListener('visibilitychange', this.wake);
+    this.reduced.addEventListener('change', this.wake);
+  }
+  setRunning(running: boolean, done?: () => void) {
+    if (running) {
+      if (this.mode === 'run') return;
+      this.mode = 'run'; this.elapsed = 0; this.done = undefined;
+    } else if (this.mode === 'run') {
+      this.exitFrom = this.current; this.mode = 'settle'; this.settling = 0; this.done = done;
+    } else if (this.mode === 'settle') { this.done = done; return; }
+    else { done?.(); }
+    this.wake();
+  }
+  private wake = () => {
+    if (this.frame !== undefined) cancelAnimationFrame(this.frame);
+    this.frame = undefined; this.lastTime = 0;
+    if (this.disposed) return;
+    if (this.reduced.matches || document.hidden) {
+      if (this.mode === 'settle') this.finish();
+      else if (this.reduced.matches) this.render(motion.getBot7State(0));
+      return;
+    }
+    if (this.mode !== 'rest') this.frame = requestAnimationFrame(this.tick);
+  };
+  private finish() {
+    this.mode = 'rest'; this.render(motion.getBot7State(0));
+    const done = this.done; this.done = undefined; done?.();
+  }
+  private tick = (now: number) => {
+    this.frame = undefined;
+    if (this.disposed) return;
+    // Cap work at 30 fps; retain elapsed time across visibility pauses.
+    if (!this.lastTime) this.lastTime = now;
+    const delta = (now - this.lastTime) / 1000;
+    if (delta >= 1 / 30) {
+      this.lastTime = now;
+      if (this.mode === 'run') { this.elapsed += delta; this.render(motion.getBot7State(orbitTime(this.elapsed))); }
+      if (this.mode === 'settle') {
+        this.settling += delta;
+        if (this.settling >= .32) this.finish();
+        else this.render(settleFrame(this.exitFrom, this.settling / .32));
+      }
+    }
+    if (this.mode !== 'rest') this.frame = requestAnimationFrame(this.tick);
+  };
+  private render(state: Frame) {
+    this.current = state;
+    const projected = this.projector.projectRoundedCube(state.bot);
+    this.body.setAttribute('d', projected.bodyPath); this.clipBody.setAttribute('d', projected.bodyPath);
+    const eyes = state.bot.showEyes === false ? [] : projected.eyes;
+    while (this.eyes.children.length > eyes.length) this.eyes.lastChild!.remove();
+    while (this.eyes.children.length < eyes.length) this.eyes.append(element('rect'));
+    eyes.forEach((eye, index) => {
+      const node = this.eyes.children[index]!;
+      for (const [key, value] of Object.entries({ x: -eye.w / 2, y: -eye.h / 2, width: eye.w, height: eye.h, rx: eye.rx, ry: eye.ry, opacity: eye.opacity ?? 1 })) node.setAttribute(key, value.toFixed(2));
+      node.setAttribute('transform', `translate(${eye.cx.toFixed(2)} ${eye.cy.toFixed(2)}) rotate(${eye.angle.toFixed(2)})`);
+    });
+    this.dots.forEach((node, index) => {
+      const dot = state.dots[index];
+      node.setAttribute('r', dot?.visible ? dot.r.toFixed(2) : '0');
+      if (dot) { node.setAttribute('cx', dot.x.toFixed(2)); node.setAttribute('cy', dot.y.toFixed(2)); }
+    });
+  }
+  destroy() {
+    this.disposed = true;
+    if (this.frame !== undefined) cancelAnimationFrame(this.frame);
+    document.removeEventListener('visibilitychange', this.wake);
+    this.reduced.removeEventListener('change', this.wake);
+    this.svg.remove(); this.done = undefined;
+  }
+}

package/src/client/style.css

@@ -0,0 +1,54 @@
+.dsh-cs-footer { margin-top: 10px; padding-top: 10px; border-top: 1px solid var(--dsw-alias-separator, #e7e7e9); }
+.dsh-cs-content { display: flex; flex-direction: column; gap: 7px; }
+.dsh-cs-button { font: inherit; font-size: 12px; line-height: 1.5; border: 0; border-radius: 7px; padding: 6px 10px; color: var(--dsw-alias-label-primary, #30343b); background: var(--dsw-alias-interactive-bg-hover, #f3f4f6); cursor: pointer; white-space: normal; overflow-wrap: anywhere; }
+.dsh-cs-button:hover { filter: brightness(.96); }
+.dsh-cs-button:focus-visible { outline: 2px solid var(--dsw-static-blue-450, #4d88f5); outline-offset: 2px; }
+.dsh-cs-button:disabled { opacity: .5; cursor: default; }
+.dsh-cs-primary { color: var(--dsw-static-blue-550, #3476e3); }
+.dsh-cs-compact { position: relative; isolation: isolate; overflow: hidden; }
+.dsh-cs-compact > .dsh-cs-button-status { position: relative; z-index: 1; display: inline-flex; align-items: center; justify-content: center; max-width: 100%; }
+.dsh-cs-sr-status { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
+.dsh-cs-compact::before { content: ''; pointer-events: none; position: absolute; inset: 0; background: linear-gradient(105deg, transparent 25%, color-mix(in srgb, currentColor 14%, transparent) 48%, transparent 72%); transform: translateX(-110%); opacity: 0; }
+.dsh-cs-content:is([data-phase="sending"], [data-phase="queued"], [data-phase="running"]) .dsh-cs-compact { opacity: 1; }
+.dsh-cs-content:is([data-phase="sending"], [data-phase="queued"], [data-phase="running"]) .dsh-cs-compact::before { opacity: 1; animation: dsh-cs-shimmer 2.6s ease-in-out infinite; }
+.dsh-cs-content[data-phase="done"] .dsh-cs-compact::before { opacity: 1; animation: dsh-cs-shimmer 900ms ease-out 1 both; }
+.dsh-cs-progress { font-variant-numeric: tabular-nums; white-space: nowrap; margin-left: 6px; flex-shrink: 0; }
+.dsh-cs-waiting-copy { display: inline-grid; min-width: 0; }
+.dsh-cs-waiting-copy > span { grid-area: 1 / 1; opacity: 0; transition: opacity 450ms ease; }
+.dsh-cs-waiting-copy > span[data-active="true"] { opacity: 1; }
+@keyframes dsh-cs-shimmer { 0% { transform: translateX(-110%); } 70%, 100% { transform: translateX(110%); } }
+@media (prefers-reduced-motion: no-preference) {
+  .dsh-cs-content:is([data-phase="idle"], [data-phase="done"]) .dsh-cs-compact:not(:disabled):is(:hover, :focus-visible)::before { opacity: 1; animation: dsh-cs-shimmer 900ms ease-out 1 both; }
+}
+.dsh-cs-status, .dsh-cs-error { font-size: 11px; line-height: 1.5; overflow-wrap: anywhere; color: var(--dsw-alias-label-secondary, #747982); }
+.dsh-cs-error { color: var(--dsw-static-red-500, #c54848); }
+.dsh-cs-hint { font-size: 10px; line-height: 1.5; text-align: center; color: var(--dsw-alias-label-tertiary, #8a9099); }
+.dsh-cs-ring { position: relative; touch-action: manipulation; -webkit-touch-callout: none; user-select: none; }
+.dsh-cs-ring-art { position: absolute; inset: auto; display: grid; place-items: center; pointer-events: none; color: var(--dsw-static-blue-550, #3476e3); }
+.dsh-cs-ring-art svg { position: absolute; width: 100%; height: 100%; overflow: visible; }
+.dsh-cs-hold { opacity: 0; transform: rotate(-90deg); }
+.dsh-cs-hold circle { fill: none; stroke: currentColor; stroke-width: 1.8; stroke-linecap: round; stroke-dasharray: 1; stroke-dashoffset: 1; }
+[data-cs-holding] .dsh-cs-hold { opacity: 1; }
+[data-cs-holding] .dsh-cs-hold circle { animation: dsh-cs-charge 650ms linear forwards; }
+@keyframes dsh-cs-charge { to { stroke-dashoffset: 0; } }
+.dsh-cs-robot { opacity: 0; transition: opacity 180ms ease, transform 320ms cubic-bezier(.2,.8,.2,1); }
+.dsh-cs-body { fill: currentColor; }
+.dsh-cs-eyes { fill: #fff; }
+.dsh-cs-dot { fill: currentColor; }
+.dsh-cs-ring > svg[viewBox="0 0 14 14"] { transition: opacity 180ms ease; }
+.dsh-cs-ring[data-cs-phase="running"] .dsh-cs-robot { opacity: 1; transform: scale(1); }
+.dsh-cs-ring:is([data-cs-phase="queued"], [data-cs-phase="sending"]) .dsh-cs-robot { opacity: .55; transform: scale(1); }
+.dsh-cs-ring[data-cs-motion="settling"] .dsh-cs-robot { opacity: 0; transform: scale(.42); }
+@media (prefers-reduced-motion: reduce) {
+  [data-cs-holding] .dsh-cs-hold circle { animation: none; stroke-dashoffset: .25; }
+  .dsh-cs-content[data-phase] .dsh-cs-compact::before { animation: none; opacity: 0; }
+  .dsh-cs-waiting-copy > span { transition: none; }
+  .dsh-cs-ring > svg[viewBox="0 0 14 14"], .dsh-cs-robot { transition: none; }
+}
+.dsh-cs-actions { display: flex; flex-direction: column; gap: 6px; }
+.dsh-cs-settings { max-width: 640px; display: flex; flex-direction: column; gap: 14px; padding: 24px; color: var(--dsw-alias-label-primary); }
+.dsh-cs-settings h2, .dsh-cs-settings p { margin: 0; }
+.dsh-cs-settings p { font-size: 13px; line-height: 1.7; color: var(--dsw-alias-label-secondary); }
+.dsh-cs-settings label { display: flex; flex-direction: column; gap: 7px; font-size: 13px; }
+.dsh-cs-settings .dsh-cs-toggle { flex-direction: row; align-items: center; }
+.dsh-cs-settings input:not([type=checkbox]), .dsh-cs-settings select { width: 100%; box-sizing: border-box; padding: 9px 10px; font: inherit; color: inherit; background: var(--dsw-alias-interactive-bg-hover, #f3f4f6); border: 1px solid var(--dsw-alias-separator, #e7e7e9); border-radius: 8px; }

package/src/client/vendor/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Bot Motion Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.