@social.io/catalog 1.3.0 → 2.1.0

package/ts_web/elements/sio-logo-render.ts

@@ -0,0 +1,367 @@
+export type TSioLogoAnimationPhase = 'in' | 'out' | 'wave' | 'loading';
+
+export interface ISioLogoRenderOptions {
+  size: number;
+  dpr: number;
+  gap: number;
+  radius: number;
+  square: boolean;
+  background: string;
+  mono: string;
+  light: boolean;
+}
+
+interface ISioLogoPoint {
+  x: number;
+  y: number;
+}
+
+interface ISioLogoFacet {
+  fill: string;
+  points: [[number, number], [number, number], [number, number]];
+}
+
+const facets: ISioLogoFacet[] = [
+  { fill: '#4AA0F5', points: [[250, 75], [150, 133.333], [250, 191.667]] },
+  { fill: '#0A5AC0', points: [[250, 75], [350, 133.333], [250, 191.667]] },
+  { fill: '#DBEBFF', points: [[150, 133.333], [250, 191.667], [150, 250]] },
+  { fill: '#A9CDF7', points: [[250, 191.667], [150, 250], [250, 308.333]] },
+  { fill: '#1E80E6', points: [[250, 191.667], [350, 250], [250, 308.333]] },
+  { fill: '#1466C6', points: [[350, 250], [250, 308.333], [350, 366.667]] },
+  { fill: '#74B4F7', points: [[250, 308.333], [350, 366.667], [250, 425]] },
+  { fill: '#1E80E6', points: [[250, 308.333], [150, 366.667], [250, 425]] },
+];
+
+const lightFills = [
+  '#4AA0F5', '#0A5AC0', '#8FBEF5', '#77ACEE',
+  '#1E80E6', '#1466C6', '#5FA6F2', '#1E80E6',
+];
+const monoOpacities = [0.78, 0.64, 0.96, 0.86, 0.72, 0.66, 0.82, 0.72];
+const tightBounds = { x: 146, y: 72, width: 208, height: 356 };
+const centerX = 250;
+const centerY = 250;
+
+export const sioLogoAspect = tightBounds.width / tightBounds.height;
+
+const centroids = facets.map((facet) => [
+  (facet.points[0][0] + facet.points[1][0] + facet.points[2][0]) / 3,
+  (facet.points[0][1] + facet.points[1][1] + facet.points[2][1]) / 3,
+]);
+
+const clamp = (value: number, minimum: number, maximum: number): number =>
+  Math.max(minimum, Math.min(maximum, value));
+
+const finiteAtLeast = (value: number, minimum: number, fallback: number): number =>
+  Number.isFinite(value) ? Math.max(minimum, value) : fallback;
+
+const normalizeOptions = (options: ISioLogoRenderOptions): ISioLogoRenderOptions => ({
+  ...options,
+  size: finiteAtLeast(options.size, 1, 40),
+  dpr: clamp(finiteAtLeast(options.dpr, 0.5, 1), 0.5, 4),
+  gap: finiteAtLeast(options.gap, 0, 2),
+  radius: finiteAtLeast(options.radius, 0, 16),
+});
+
+const inset = (
+  points: ISioLogoFacet['points'],
+  gap: number,
+): ISioLogoPoint[] => {
+  if (gap <= 0) return points.map(([x, y]) => ({ x, y }));
+  const centroidX = (points[0][0] + points[1][0] + points[2][0]) / 3;
+  const centroidY = (points[0][1] + points[1][1] + points[2][1]) / 3;
+  const lines: Array<ISioLogoPoint & { dx: number; dy: number }> = [];
+
+  for (let index = 0; index < points.length; index += 1) {
+    const start = points[index];
+    const end = points[(index + 1) % points.length];
+    let deltaX = end[0] - start[0];
+    let deltaY = end[1] - start[1];
+    const length = Math.hypot(deltaX, deltaY);
+    deltaX /= length;
+    deltaY /= length;
+    let normalX = -deltaY;
+    let normalY = deltaX;
+    const middleX = (start[0] + end[0]) / 2;
+    const middleY = (start[1] + end[1]) / 2;
+    if ((centroidX - middleX) * normalX + (centroidY - middleY) * normalY < 0) {
+      normalX = -normalX;
+      normalY = -normalY;
+    }
+    lines.push({
+      x: start[0] + normalX * gap,
+      y: start[1] + normalY * gap,
+      dx: deltaX,
+      dy: deltaY,
+    });
+  }
+
+  return lines.map((line, index) => {
+    const previous = lines[(index - 1 + lines.length) % lines.length];
+    const denominator = previous.dx * line.dy - previous.dy * line.dx;
+    const distance =
+      ((line.x - previous.x) * line.dy - (line.y - previous.y) * line.dx) /
+      denominator;
+    return {
+      x: previous.x + previous.dx * distance,
+      y: previous.y + previous.dy * distance,
+    };
+  });
+};
+
+const createFacetPath = (
+  points: ISioLogoFacet['points'],
+  gap: number,
+  radius: number,
+): Path2D => {
+  const insetPoints = inset(points, gap);
+  const path = new Path2D();
+  if (radius <= 0) {
+    path.moveTo(insetPoints[0].x, insetPoints[0].y);
+    for (let index = 1; index < insetPoints.length; index += 1) {
+      path.lineTo(insetPoints[index].x, insetPoints[index].y);
+    }
+    path.closePath();
+    return path;
+  }
+
+  for (let index = 0; index < insetPoints.length; index += 1) {
+    const vertex = insetPoints[index];
+    const previous = insetPoints[(index - 1 + insetPoints.length) % insetPoints.length];
+    const next = insetPoints[(index + 1) % insetPoints.length];
+    const previousDistance = Math.hypot(previous.x - vertex.x, previous.y - vertex.y);
+    const nextDistance = Math.hypot(next.x - vertex.x, next.y - vertex.y);
+    const previousRadius = Math.min(radius, previousDistance * 0.5);
+    const nextRadius = Math.min(radius, nextDistance * 0.5);
+    const entry = {
+      x: vertex.x + ((previous.x - vertex.x) / previousDistance) * previousRadius,
+      y: vertex.y + ((previous.y - vertex.y) / previousDistance) * previousRadius,
+    };
+    const exit = {
+      x: vertex.x + ((next.x - vertex.x) / nextDistance) * nextRadius,
+      y: vertex.y + ((next.y - vertex.y) / nextDistance) * nextRadius,
+    };
+    if (index === 0) path.moveTo(entry.x, entry.y);
+    else path.lineTo(entry.x, entry.y);
+    path.quadraticCurveTo(vertex.x, vertex.y, exit.x, exit.y);
+  }
+  path.closePath();
+  return path;
+};
+
+const easeOutCubic = (progress: number): number => 1 - Math.pow(1 - progress, 3);
+const easeOutBack = (progress: number): number => {
+  const coefficient = 1.70158;
+  return 1 + (coefficient + 1) * Math.pow(progress - 1, 3) + coefficient * Math.pow(progress - 1, 2);
+};
+const easeInCubic = (progress: number): number => progress * progress * progress;
+const easeInBack = (progress: number): number => {
+  const coefficient = 1.70158;
+  return (coefficient + 1) * progress * progress * progress - coefficient * progress * progress;
+};
+
+export class SioLogoRenderer {
+  private options: ISioLogoRenderOptions;
+  private frameHandle: number | null = null;
+  private phase: TSioLogoAnimationPhase | null = null;
+  private startedAt = 0;
+  private stagger = 70;
+  private duration = 560;
+  private totalDuration = 0;
+  private backingWidth = 0;
+  private backingHeight = 0;
+  private scale = 1;
+  private offsetX = 0;
+  private offsetY = 0;
+  private paths: Path2D[] = [];
+  private loadingPaths: Path2D[] = [];
+  private fills: string[] = [];
+  private opacities: number[] = [];
+
+  constructor(
+    private readonly context: CanvasRenderingContext2D,
+    options: ISioLogoRenderOptions,
+  ) {
+    this.options = normalizeOptions(options);
+    this.rebuild();
+  }
+
+  public setOptions(options: ISioLogoRenderOptions): void {
+    this.options = normalizeOptions(options);
+    this.rebuild();
+    if (!this.phase) this.drawStatic();
+  }
+
+  public drawStatic(): void {
+    this.clearCanvas();
+    for (let index = 0; index < facets.length; index += 1) {
+      this.paint(index, 0, 0, 0, 1, this.opacities[index], this.paths[index]);
+    }
+    this.context.globalAlpha = 1;
+  }
+
+  public clear(): void {
+    this.stop();
+    this.clearCanvas();
+  }
+
+  public start(phase: TSioLogoAnimationPhase): void {
+    this.stop();
+    this.phase = phase;
+    this.startedAt = performance.now();
+    this.stagger = phase === 'wave' ? 55 : 70;
+    this.duration = phase === 'wave' ? 420 : 560;
+    this.totalDuration = this.stagger * (facets.length - 1) + this.duration;
+
+    const drawFrame = (time: number): void => {
+      if (!this.phase) return;
+      const elapsed = time - this.startedAt;
+      this.drawAnimationFrame(elapsed);
+      if (this.phase !== 'loading' && elapsed >= this.totalDuration) {
+        this.settle();
+        return;
+      }
+      this.frameHandle = requestAnimationFrame(drawFrame);
+    };
+    this.frameHandle = requestAnimationFrame(drawFrame);
+  }
+
+  public stop(): void {
+    if (this.frameHandle !== null) {
+      cancelAnimationFrame(this.frameHandle);
+      this.frameHandle = null;
+    }
+    this.phase = null;
+  }
+
+  private rebuild(): void {
+    const { size, dpr, square, light, mono, gap, radius } = this.options;
+    this.backingWidth = Math.round((square ? size : size * sioLogoAspect) * dpr);
+    this.backingHeight = Math.round(size * dpr);
+    this.context.canvas.width = this.backingWidth;
+    this.context.canvas.height = this.backingHeight;
+    if (square) {
+      this.scale = this.backingWidth / 500;
+      this.offsetX = 0;
+      this.offsetY = 0;
+    } else {
+      this.scale = this.backingHeight / tightBounds.height;
+      this.offsetX =
+        -tightBounds.x * this.scale +
+        (this.backingWidth - tightBounds.width * this.scale) / 2;
+      this.offsetY = -tightBounds.y * this.scale;
+    }
+    this.paths = facets.map((facet) => createFacetPath(facet.points, gap, radius));
+    this.loadingPaths = facets.map((facet) => createFacetPath(facet.points, gap + 3, 90));
+    this.fills = facets.map((facet, index) => mono || (light ? lightFills[index] : facet.fill));
+    this.opacities = facets.map((_, index) => (mono ? monoOpacities[index] : 1));
+  }
+
+  private clearCanvas(): void {
+    this.context.setTransform(1, 0, 0, 1, 0, 0);
+    this.context.clearRect(0, 0, this.backingWidth, this.backingHeight);
+    const { background } = this.options;
+    if (background && background !== 'transparent' && background !== 'none') {
+      this.context.fillStyle = background;
+      this.context.fillRect(0, 0, this.backingWidth, this.backingHeight);
+    }
+  }
+
+  private paint(
+    index: number,
+    translateX: number,
+    translateY: number,
+    rotation: number,
+    scale: number,
+    opacity: number,
+    path: Path2D,
+  ): void {
+    const [centroidX, centroidY] = centroids[index];
+    this.context.setTransform(this.scale, 0, 0, this.scale, this.offsetX, this.offsetY);
+    this.context.translate(translateX, translateY);
+    this.context.translate(centroidX, centroidY);
+    this.context.rotate((rotation * Math.PI) / 180);
+    this.context.scale(scale, scale);
+    this.context.translate(-centroidX, -centroidY);
+    this.context.globalAlpha = opacity;
+    this.context.fillStyle = this.fills[index];
+    this.context.fill(path);
+  }
+
+  private drawAnimationFrame(elapsed: number): void {
+    this.clearCanvas();
+    const activePhase = this.phase;
+    for (let index = 0; index < facets.length; index += 1) {
+      const [centroidX, centroidY] = centroids[index];
+      let translateX = 0;
+      let translateY = 0;
+      let rotation = 0;
+      let scale = 1;
+      let opacity = this.opacities[index];
+      let path = this.paths[index];
+
+      if (activePhase === 'in') {
+        const progress = clamp((elapsed - index * this.stagger) / this.duration, 0, 1);
+        const eased = easeOutCubic(progress);
+        translateX = (centerX - centroidX) * (1 - eased);
+        translateY = (centerY - centroidY) * (1 - eased);
+        rotation = (1 - eased) * -16;
+        scale = easeOutBack(progress);
+        opacity = clamp(progress * 1.6, 0, 1) * this.opacities[index];
+      } else if (activePhase === 'out') {
+        const reverseIndex = facets.length - 1 - index;
+        const progress = clamp((elapsed - reverseIndex * this.stagger) / this.duration, 0, 1);
+        const eased = easeInCubic(progress);
+        translateX = (centerX - centroidX) * eased;
+        translateY = (centerY - centroidY) * eased;
+        rotation = progress * 16;
+        scale = Math.max(0, 1 - easeInBack(progress));
+        opacity = clamp(1 - progress * 1.3, 0, 1) * this.opacities[index];
+      } else if (activePhase === 'wave') {
+        const progress = clamp((elapsed - index * this.stagger) / this.duration, 0, 1);
+        const pulse = Math.sin(progress * Math.PI);
+        const radialX = centroidX - centerX;
+        const radialY = centroidY - centerY;
+        const radialLength = Math.hypot(radialX, radialY) || 1;
+        translateX = (radialX / radialLength) * 16 * pulse;
+        translateY = (radialY / radialLength) * 16 * pulse;
+        scale = 1 - 0.08 * pulse;
+      } else if (activePhase === 'loading') {
+        const growth = clamp(elapsed / 650, 0, 1);
+        const easedGrowth = growth < 0.5
+          ? 2 * growth * growth
+          : 1 - Math.pow(-2 * growth + 2, 2) / 2;
+        const looping = elapsed >= 650;
+        const spin = (elapsed / 1500) * 2 * Math.PI;
+        const angle = -Math.PI / 2 + index * Math.PI / 4 + spin;
+        const destinationX = centerX + 120 * Math.cos(angle);
+        const destinationY = centerY + 120 * Math.sin(angle);
+        const brightness = 1 - index / facets.length;
+        translateX = (destinationX - centroidX) * easedGrowth;
+        translateY = (destinationY - centroidY) * easedGrowth;
+        scale =
+          (1 + (0.62 - 1) * easedGrowth) *
+          (looping ? 0.72 + 0.28 * brightness : 1);
+        opacity = (looping ? 0.28 + 0.72 * brightness : 1) * this.opacities[index];
+        path = looping
+          ? this.loadingPaths[index]
+          : createFacetPath(
+            facets[index].points,
+            this.options.gap + 3 * easedGrowth,
+            this.options.radius + (90 - this.options.radius) * easedGrowth,
+          );
+      }
+
+      this.paint(index, translateX, translateY, rotation, scale, opacity, path);
+    }
+    this.context.globalAlpha = 1;
+  }
+
+  private settle(): void {
+    const finishedPhase = this.phase;
+    this.frameHandle = null;
+    this.phase = null;
+    if (finishedPhase === 'out') this.clearCanvas();
+    else this.drawStatic();
+    this.context.globalAlpha = 1;
+  }
+}

package/ts_web/elements/sio-logo.ts

@@ -0,0 +1,311 @@
+import {
+  DeesElement,
+  css,
+  customElement,
+  html,
+  property,
+  type TemplateResult,
+} from '@design.estate/dees-element';
+import { SioLogoRenderer, sioLogoAspect } from './sio-logo-render.js';
+import { sioElementStyles } from './tokens.js';
+
+export type TSioLogoTheme = 'auto' | 'light' | 'dark';
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'sio-logo': SioLogo;
+  }
+}
+
+/**
+ * The social.io faceted S brand mark from the v8 design prototype.
+ *
+ * The canvas renderer preserves the exact eight-facet geometry and supports
+ * entrance, hover-wave, dismiss, and loading animations. Motion is disabled
+ * when the visitor requests reduced motion.
+ */
+@customElement('sio-logo')
+export class SioLogo extends DeesElement {
+  public static demo = () => html`
+    <div style="display:flex;align-items:center;gap:32px;padding:24px;background:#101012;">
+      <sio-logo size="120" theme="dark"></sio-logo>
+      <sio-logo size="120" square background="#556270" radius="22" theme="dark"></sio-logo>
+      <sio-logo size="120" loading theme="dark"></sio-logo>
+      <sio-logo size="120" mono="#ffffff" no-entrance theme="dark"></sio-logo>
+    </div>
+  `;
+
+  /** rendered height in CSS pixels; tight-crop width follows the brand aspect */
+  @property({ type: Number })
+  public accessor size = 40;
+
+  @property({ type: String })
+  public accessor background = 'transparent';
+
+  /** inward inset per facet, in 500px design-grid units */
+  @property({ type: Number })
+  public accessor gap = 2;
+
+  /** facet corner radius, in 500px design-grid units */
+  @property({ type: Number })
+  public accessor radius = 16;
+
+  /** render on a square tile instead of the tight S crop */
+  @property({ type: Boolean })
+  public accessor square = false;
+
+  /** collapse the palette to one color while retaining facet depth */
+  @property({ type: String })
+  public accessor mono = '';
+
+  /** backdrop palette; auto follows the nearest opaque surface */
+  @property({ type: String })
+  public accessor theme: TSioLogoTheme = 'auto';
+
+  @property({ type: Boolean, reflect: true })
+  public accessor loading = false;
+
+  @property({ type: Boolean, attribute: 'no-entrance' })
+  public accessor noEntrance = false;
+
+  @property({ type: Boolean, attribute: 'no-hover' })
+  public accessor noHover = false;
+
+  public static styles = [
+    ...sioElementStyles,
+    css`
+      :host {
+        display: inline-flex;
+        flex: none;
+        line-height: 0;
+      }
+      canvas {
+        display: block;
+      }
+    `,
+  ];
+
+  private renderer: SioLogoRenderer | null = null;
+  private themeObserver: MutationObserver | null = null;
+  private colorSchemeMedia: MediaQueryList | null = null;
+  private reducedMotionMedia: MediaQueryList | null = null;
+  private lastDevicePixelRatio = 0;
+  private lifecycleGeneration = 0;
+
+  private readonly handlePointerEnter = (): void => {
+    if (!this.noHover && !this.loading && !this.prefersReducedMotion()) this.wave();
+  };
+
+  private readonly handleAmbientChange = (): void => {
+    this.syncRenderer(this.loading ? 'loading' : null);
+  };
+
+  private readonly handleReducedMotionChange = (): void => {
+    this.syncRenderer(this.loading ? 'loading' : null);
+  };
+
+  private readonly handleResize = (): void => {
+    const currentDevicePixelRatio = window.devicePixelRatio || 1;
+    if (currentDevicePixelRatio === this.lastDevicePixelRatio) return;
+    this.syncRenderer(this.loading ? 'loading' : null);
+  };
+
+  public async connectedCallback(): Promise<void> {
+    const generation = ++this.lifecycleGeneration;
+    const connection = super.connectedCallback();
+    this.ensureAccessibleHost();
+    this.addEventListener('mouseenter', this.handlePointerEnter);
+    window.addEventListener('resize', this.handleResize);
+    this.observeReducedMotion();
+    await connection;
+    if (!this.isConnected || generation !== this.lifecycleGeneration) return;
+    if (this.hasUpdated) {
+      this.observeAmbientTheme();
+      this.syncRenderer(this.loading ? 'loading' : null);
+    }
+  }
+
+  public async disconnectedCallback(): Promise<void> {
+    const generation = ++this.lifecycleGeneration;
+    this.cleanupOwnedResources();
+    await super.disconnectedCallback();
+    if (!this.isConnected && generation === this.lifecycleGeneration) {
+      this.cleanupOwnedResources();
+    }
+  }
+
+  private cleanupOwnedResources(): void {
+    this.removeEventListener('mouseenter', this.handlePointerEnter);
+    window.removeEventListener('resize', this.handleResize);
+    this.stopAmbientThemeObservation();
+    this.stopReducedMotionObservation();
+    this.renderer?.stop();
+  }
+
+  public render(): TemplateResult {
+    const height = this.normalizedSize;
+    const width = this.square ? height : Math.round(height * sioLogoAspect);
+    return html`<canvas aria-hidden="true" style="width:${width}px;height:${height}px"></canvas>`;
+  }
+
+  public firstUpdated(changedProperties: Map<PropertyKey, unknown>): void {
+    super.firstUpdated(changedProperties);
+    const canvas = this.shadowRoot?.querySelector<HTMLCanvasElement>('canvas');
+    const context = canvas?.getContext('2d');
+    if (!context) return;
+    this.renderer = new SioLogoRenderer(context, this.getRendererOptions());
+    if (!this.isConnected) {
+      this.renderer.drawStatic();
+      return;
+    }
+    this.observeAmbientTheme();
+    if (this.loading && !this.prefersReducedMotion()) this.renderer.start('loading');
+    else if (!this.noEntrance && !this.prefersReducedMotion()) this.renderer.start('in');
+    else this.renderer.drawStatic();
+  }
+
+  public updated(changedProperties: Map<PropertyKey, unknown>): void {
+    if (!this.isConnected) {
+      this.stopAmbientThemeObservation();
+      this.renderer?.stop();
+      return;
+    }
+    const redrawProperties: PropertyKey[] = [
+      'size',
+      'gap',
+      'radius',
+      'square',
+      'background',
+      'mono',
+      'theme',
+    ];
+    if (redrawProperties.some((propertyName) => changedProperties.has(propertyName))) {
+      this.syncRenderer(this.loading ? 'loading' : null);
+    }
+    if (changedProperties.has('theme')) {
+      this.stopAmbientThemeObservation();
+      this.observeAmbientTheme();
+    }
+    if (changedProperties.has('loading')) {
+      this.syncRenderer(this.loading ? 'loading' : null);
+    }
+  }
+
+  protected themeChanged(): void {
+    this.syncRenderer(this.loading ? 'loading' : null);
+  }
+
+  public play(): void {
+    if (!this.renderer || !this.isConnected) return;
+    if (this.prefersReducedMotion()) this.renderer.drawStatic();
+    else this.renderer.start('in');
+  }
+
+  public wave(): void {
+    if (!this.renderer || !this.isConnected) return;
+    if (this.prefersReducedMotion()) this.renderer.drawStatic();
+    else this.renderer.start('wave');
+  }
+
+  public dismiss(): void {
+    if (!this.renderer || !this.isConnected) return;
+    if (this.prefersReducedMotion()) this.renderer.clear();
+    else this.renderer.start('out');
+  }
+
+  private get normalizedSize(): number {
+    return Number.isFinite(this.size) ? Math.max(1, this.size) : 40;
+  }
+
+  private getRendererOptions() {
+    this.lastDevicePixelRatio = window.devicePixelRatio || 1;
+    return {
+      size: this.normalizedSize,
+      dpr: this.lastDevicePixelRatio,
+      gap: Number.isFinite(this.gap) ? Math.max(0, this.gap) : 2,
+      radius: Number.isFinite(this.radius) ? Math.max(0, this.radius) : 16,
+      square: this.square,
+      background: this.background,
+      mono: this.mono,
+      light: this.isLightBackdrop(),
+    };
+  }
+
+  private syncRenderer(animation: 'loading' | null = null): void {
+    if (!this.renderer) return;
+    this.renderer.stop();
+    this.renderer.setOptions(this.getRendererOptions());
+    if (animation && this.isConnected && !this.prefersReducedMotion()) {
+      this.renderer.start(animation);
+    }
+    else this.renderer.drawStatic();
+  }
+
+  private prefersReducedMotion(): boolean {
+    return this.reducedMotionMedia?.matches ??
+      window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ??
+      false;
+  }
+
+  private isLightBackdrop(): boolean {
+    if (this.theme === 'light') return true;
+    if (this.theme === 'dark') return false;
+
+    let element: Element | null = this;
+    while (element) {
+      const color = getComputedStyle(element).backgroundColor;
+      const match = color.match(
+        /rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:\s*[,/]\s*([\d.]+))?\s*\)/,
+      );
+      if (match) {
+        const alpha = match[4] === undefined ? 1 : Number.parseFloat(match[4]);
+        if (alpha > 0.2) {
+          const luminance =
+            (0.2126 * Number(match[1]) +
+              0.7152 * Number(match[2]) +
+              0.0722 * Number(match[3])) /
+            255;
+          return luminance > 0.55;
+        }
+      }
+      const root = element.getRootNode();
+      element = element.parentElement || (root instanceof ShadowRoot ? root.host : null);
+    }
+    return window.matchMedia?.('(prefers-color-scheme: light)').matches ?? false;
+  }
+
+  private observeAmbientTheme(): void {
+    if (this.theme !== 'auto' || this.themeObserver) return;
+    this.themeObserver = new MutationObserver(this.handleAmbientChange);
+    this.themeObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-sio-theme', 'data-theme', 'class', 'style'],
+    });
+    this.colorSchemeMedia = window.matchMedia?.('(prefers-color-scheme: light)') ?? null;
+    this.colorSchemeMedia?.addEventListener('change', this.handleAmbientChange);
+  }
+
+  private stopAmbientThemeObservation(): void {
+    this.themeObserver?.disconnect();
+    this.themeObserver = null;
+    this.colorSchemeMedia?.removeEventListener('change', this.handleAmbientChange);
+    this.colorSchemeMedia = null;
+  }
+
+  private observeReducedMotion(): void {
+    if (this.reducedMotionMedia) return;
+    this.reducedMotionMedia = window.matchMedia?.('(prefers-reduced-motion: reduce)') ?? null;
+    this.reducedMotionMedia?.addEventListener('change', this.handleReducedMotionChange);
+  }
+
+  private stopReducedMotionObservation(): void {
+    this.reducedMotionMedia?.removeEventListener('change', this.handleReducedMotionChange);
+    this.reducedMotionMedia = null;
+  }
+
+  private ensureAccessibleHost(): void {
+    if (this.hasAttribute('aria-hidden')) return;
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'img');
+    if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'social.io');
+  }
+}