refactor: move frontend/ to examples/frontend/

The Lit + Vite HOMECORE web UI is an example consumer of the
sensing stack, not a top-level deliverable — relocate it under
examples/ alongside the other sensor and dashboard demos.

Add an entry to examples/README.md so it's discoverable.

Co-Authored-By: claude-flow <ruv@ruv.net>

examples/frontend/src/__tests__/StateCard.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Unit tests for <hc-state-card>.
+ * Verifies that the component renders entity_id and state value into the DOM.
+ *
+ * Uses jsdom (via vitest environment) — no real browser required.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import type { StateView } from '../api/types.js';
+
+// Register the custom element before tests run
+beforeAll(async () => {
+  // jsdom does not support Lit's adoptedStyleSheets; suppress the error.
+  if (typeof document !== 'undefined' && !document.adoptedStyleSheets) {
+    Object.defineProperty(document, 'adoptedStyleSheets', { value: [], writable: true });
+  }
+  await import('../components/StateCard.js');
+});
+
+function makeState(overrides: Partial<StateView> = {}): StateView {
+  return {
+    entity_id: 'light.living_room',
+    state: 'on',
+    attributes: { brightness: 255 },
+    last_changed: '2026-05-25T10:00:00Z',
+    last_updated: '2026-05-25T10:00:00Z',
+    context: { id: 'abc123', user_id: null, parent_id: null },
+    ...overrides,
+  };
+}
+
+describe('StateCard', () => {
+  it('renders entity_id in the DOM', async () => {
+    const el = document.createElement('hc-state-card') as HTMLElement & { state: StateView };
+    el.state = makeState();
+    document.body.appendChild(el);
+
+    // Lit renders synchronously into shadow root after a microtask
+    await el.updateComplete;
+
+    const shadowRoot = el.shadowRoot!;
+    const entityEl = shadowRoot.querySelector('.entity-id');
+    expect(entityEl).not.toBeNull();
+    expect(entityEl!.textContent).toContain('light.living_room');
+
+    document.body.removeChild(el);
+  });
+
+  it('renders the state value', async () => {
+    const el = document.createElement('hc-state-card') as HTMLElement & { state: StateView };
+    el.state = makeState({ state: 'off' });
+    document.body.appendChild(el);
+
+    await el.updateComplete;
+
+    const stateEl = el.shadowRoot!.querySelector('.state-value');
+    expect(stateEl).not.toBeNull();
+    expect(stateEl!.textContent).toBe('off');
+
+    document.body.removeChild(el);
+  });
+
+  it('applies .off badge class for unavailable state', async () => {
+    const el = document.createElement('hc-state-card') as HTMLElement & { state: StateView };
+    el.state = makeState({ state: 'unavailable' });
+    document.body.appendChild(el);
+
+    await el.updateComplete;
+
+    const badge = el.shadowRoot!.querySelector('.badge.off');
+    expect(badge).not.toBeNull();
+
+    document.body.removeChild(el);
+  });
+});
+
+// Augment for updateComplete
+declare global {
+  interface HTMLElement {
+    updateComplete: Promise<boolean>;
+  }
+}

examples/frontend/src/__tests__/client.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Unit tests for HomecoreClient REST methods.
+ * Mocks global `fetch` and asserts correct URL + Authorization header.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { HomecoreClient } from '../api/client.js';
+
+describe('HomecoreClient', () => {
+  const token = 'test-bearer-token';
+  let client: HomecoreClient;
+  let fetchSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    client = new HomecoreClient({ token });
+    fetchSpy = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    } as Response);
+    vi.stubGlobal('fetch', fetchSpy);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('getStates() GETs /api/states with the bearer header', async () => {
+    await client.getStates();
+
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+
+    expect(url).toBe('/api/states');
+    expect((init.headers as Record<string, string>)['Authorization']).toBe(`Bearer ${token}`);
+    expect(init.method).toBe('GET');
+  });
+
+  it('getState() GETs /api/states/:entity_id with the bearer header', async () => {
+    fetchSpy.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ entity_id: 'light.living', state: 'on', attributes: {}, last_changed: '', last_updated: '', context: { id: 'x', user_id: null, parent_id: null } }),
+    } as Response);
+
+    await client.getState('light.living');
+
+    const [url] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('/api/states/light.living');
+  });
+
+  it('getConfig() GETs /api/config', async () => {
+    fetchSpy.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ location_name: 'Home', version: '0.1.0', state: 'RUNNING', components: [] }),
+    } as Response);
+
+    await client.getConfig();
+
+    const [url] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('/api/config');
+  });
+
+  it('throws on non-OK response', async () => {
+    fetchSpy.mockResolvedValueOnce({ ok: false, status: 401, statusText: 'Unauthorized' } as Response);
+
+    await expect(client.getStates()).rejects.toThrow('401');
+  });
+});

examples/frontend/src/__tests__/tokens.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Validates that tokens.css contains all 16 documented HOMECORE design tokens.
+ * Reads the file from disk and checks for each CSS custom property name.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const tokensPath = resolve(__dirname, '../styles/tokens.css');
+const css = readFileSync(tokensPath, 'utf-8');
+
+/**
+ * The 16 design tokens from ADR-131 §9 / HOMECORE-FRONTEND-design-recon.md §1.
+ * 4 surfaces + 2 text + 6 accent/status + 2 border/ring + 2 radius = 16 tokens.
+ */
+const REQUIRED_TOKENS = [
+  // Surfaces (4)
+  '--hc-bg',
+  '--hc-surface-card',
+  '--hc-surface-elevated',
+  '--hc-surface-overlay',
+  // Text (2)
+  '--hc-text',
+  '--hc-text-muted',
+  // Accent palette (6)
+  '--hc-primary',
+  '--hc-primary-fg',
+  '--hc-accent',
+  '--hc-accent-fg',
+  '--hc-destructive',
+  '--hc-warning',
+  // Borders & rings (2)
+  '--hc-border',
+  '--hc-ring',
+  // Radii (2)
+  '--hc-radius',
+  '--hc-radius-sm',
+] as const;
+
+describe('tokens.css', () => {
+  it('contains all 16 documented design tokens', () => {
+    for (const token of REQUIRED_TOKENS) {
+      expect(css, `Missing token: ${token}`).toContain(token);
+    }
+  });
+
+  it('has exactly 16 (or more) --hc- custom properties', () => {
+    const matches = css.match(/--hc-[\w-]+\s*:/g) ?? [];
+    // De-duplicate (token may appear in comments)
+    const unique = new Set(matches.map(m => m.replace(/\s*:/, '')));
+    expect(unique.size).toBeGreaterThanOrEqual(16);
+  });
+
+  it('defines the teal primary token with the correct hue value', () => {
+    // --hc-primary must reference HSL hue 185 (teal, from cognitum-v0)
+    expect(css).toMatch(/--hc-primary\s*:\s*hsl\(185/);
+  });
+
+  it('defines the green accent token (#26d867)', () => {
+    // --hc-accent must reference HSL 142 70% 50%
+    expect(css).toMatch(/--hc-accent\s*:\s*hsl\(142/);
+  });
+});