## Demo: queue

### Queue.svelte
```svelte
<script lang="ts">
  import DemoPage from '../../components/DemoPage.svelte';
  import QueueWidget from './QueueWidget.svelte';
  import { loadSources } from '../../components/utils.ts';
  import { files } from './files.ts';
  import type { QueueStatus } from './types.ts';

  const sources = await loadSources(files);

  let { initial, suggestedUser }: { initial: QueueStatus; suggestedUser: string } = $props();
</script>

<DemoPage
  title="Background jobs with queues"
  description="A Mochi.queue(name) bundles a job channel with its process() consumer, declared once in the Mochi.serve() queues array. The form enqueues a job, the queue processes it ~700ms later, and the result streams back live."
  {sources}
>
  <p>
    The page action calls <code>notificationQueue.add({'{ user }'})</code> on the descriptor returned by
    <code>Mochi.queue('demo-notifications', …)</code>. Its <code>process</code> function — with
    <code>concurrency: 2</code>, mounted via <code>queues: [notificationQueue]</code> in
    <code>Mochi.serve()</code> — picks the job up and records it. Initial state comes from
    <code>serverProps</code>; a <code>Mochi.sse()</code> route then pushes each completion in realtime — no polling.
  </p>
  <QueueWidget {initial} {suggestedUser} mochi:hydrate />
</DemoPage>

<style>
  p {
    margin: 0 0 0.5rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### QueueWidget.svelte
```svelte
<script lang="ts">
  import { enhance } from 'mochi-framework';
  import type { MochiSubmitFunction } from 'mochi-framework';
  import type { ProcessedEntry, QueueStatus } from './types.ts';
  import { randomUsername } from './usernames.ts';

  let { initial, suggestedUser }: { initial: QueueStatus; suggestedUser: string } = $props();

  // Seed from the serverProps snapshot; the SSE stream then owns these server-global counters.
  // svelte-ignore state_referenced_locally
  let pending = $state(initial.inFlight);
  // svelte-ignore state_referenced_locally
  let processed = $state<ProcessedEntry[]>(initial.processed);
  // svelte-ignore state_referenced_locally
  let processedTotal = $state(initial.processedTotal);
  // Preloaded server-side so SSR and hydration match; refreshed after each submit.
  // svelte-ignore state_referenced_locally
  let username = $state(suggestedUser);
  let lastQueued = $state<string | null>(null);

  $effect(() => {
    const source = new EventSource('/demos/queue/events/');
    source.addEventListener('message', (e) => {
      const status = JSON.parse(e.data) as QueueStatus;
      pending = status.inFlight;
      processed = status.processed;
      processedTotal = status.processedTotal;
    });

    const close = () => source.close();
    window.addEventListener('pagehide', close);
    return () => {
      window.removeEventListener('pagehide', close);
      close();
    };
  });

  const handleEnqueue: MochiSubmitFunction<{ queued: string }> = () => {
    return ({ result }) => {
      if (result.type === 'success' && result.data) {
        lastQueued = result.data.queued;
        username = randomUsername();
      }
    };
  };
</script>

<div class="queue">
  <form method="POST" action="?/enqueue" {@attach enhance(handleEnqueue)}>
    <label>
      <span>Username</span>
      <input type="text" name="username" placeholder="alice" autocomplete="off" bind:value={username} />
    </label>
    <button type="submit">Enqueue notification</button>
  </form>

  <div class="status">
    <div class="stat">
      <span class="num">{pending}</span>
      <span class="lbl">in flight</span>
    </div>
    <div class="stat">
      <span class="num">{processedTotal}</span>
      <span class="lbl">processed</span>
    </div>
  </div>

  {#if lastQueued}
    <p class="hint">Queued a notification for <code>{lastQueued}</code>.</p>
  {/if}

  <h3>Recently processed</h3>
  {#if processed.length === 0}
    <p class="empty">No notifications processed yet. Enqueue one above.</p>
  {:else}
    <ul>
      <!-- {entry.user} is free-text from the user; Svelte escapes it on render, so it's XSS-safe. -->
      {#each processed as entry (entry.at + entry.user)}
        <li>
          <code>{entry.user}</code>
          <span class="time">{new Date(entry.at).toLocaleTimeString()} · {(entry.ms / 1000).toFixed(2)}s</span>
        </li>
      {/each}
    </ul>
  {/if}
</div>

<style>
  .queue {
    display: flex;
    flex-direction: column;
    gap: 1rem;
    margin-top: 0.75rem;
  }

  form {
    display: flex;
    flex-direction: column;
    gap: 0.6rem;
    align-items: flex-start;
  }

  label {
    display: flex;
    flex-direction: column;
    gap: 0.25rem;
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  input {
    padding: 0.5rem 0.7rem;
    background: var(--surface);
    color: var(--text);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 1rem;
    width: 16rem;
  }

  button {
    padding: 0.5rem 1rem;
    background: var(--accent);
    color: var(--accent-text);
    border: 1px solid var(--accent);
    border-radius: var(--radius-md);
    font-family: inherit;
    font-size: 0.95rem;
    font-weight: 600;
    cursor: pointer;
  }

  button:hover {
    background: var(--accent-hover);
    border-color: var(--accent-hover);
  }

  .status {
    display: flex;
    gap: 1.5rem;
  }

  .stat {
    display: flex;
    flex-direction: column;
    align-items: center;
    padding: 0.5rem 1rem;
    background: var(--surface);
    border: 1px solid var(--border);
    border-radius: var(--radius-md);
    min-width: 5rem;
  }

  .num {
    font-size: 1.5rem;
    font-weight: 700;
    font-family: var(--font-mono);
    color: var(--text);
  }

  .lbl {
    font-size: 0.75rem;
    color: var(--text-subtle);
  }

  .hint {
    margin: 0;
    font-size: 0.85rem;
    color: var(--text-muted);
  }

  h3 {
    margin: 0.5rem 0 0;
    font-size: 0.9rem;
    font-weight: 600;
    color: var(--text-muted);
  }

  .empty {
    margin: 0;
    font-size: 0.85rem;
    color: var(--text-subtle);
  }

  ul {
    list-style: none;
    margin: 0;
    padding: 0;
    display: flex;
    flex-direction: column;
    gap: 0.35rem;
  }

  li {
    display: flex;
    justify-content: space-between;
    align-items: center;
    padding: 0.4rem 0.7rem;
    background: var(--surface);
    border: 1px solid var(--border);
    border-radius: var(--radius-sm);
    font-size: 0.85rem;
  }

  .time {
    color: var(--text-subtle);
    font-family: var(--font-mono);
    font-size: 0.8rem;
  }

  code {
    background: var(--code-bg);
    color: var(--code-accent);
    padding: 0.05rem 0.35rem;
    border-radius: var(--radius-sm);
    font-family: var(--font-mono);
    font-size: 0.85rem;
  }
</style>
```

### queue.server.ts
```ts
import { Mochi, mochiEvents } from 'mochi-framework';
import type { NotificationJob, ProcessedEntry, QueueStatus } from './types';

export const QUEUE_NAME = 'demo-notifications';

// `inFlight` is tracked off the event bus, not per request, so every connected browser sees the same numbers.
const processed: ProcessedEntry[] = [];
let processedTotal = 0;
let inFlight = 0;

mochiEvents.on('queue:added', (e) => {
  if (e.queue === QUEUE_NAME) {
    inFlight++;
  }
});
const settle = (e: { queue: string }) => {
  if (e.queue === QUEUE_NAME) {
    inFlight = Math.max(0, inFlight - 1);
  }
};
mochiEvents.on('queue:completed', settle);
mochiEvents.on('queue:failed', settle);

// The site rides the default `queueStorage: 'memory'`, so the demo writes no queue file into the working dir;
// set `Mochi.serve({ queueStorage })` to persist.
export const notificationQueue = Mochi.queue<NotificationJob>(QUEUE_NAME, {
  concurrency: 2,
  process: async (job) => {
    // Simulate delivery latency so the UI shows the queued → processing → done transition.
    const start = Date.now();
    await Bun.sleep(500 + Math.random() * 1500);
    processed.push({ user: job.data.user, at: Date.now(), ms: Date.now() - start });
    if (processed.length > 20) {
      processed.shift();
    }
    processedTotal++;
    return { delivered: true };
  },
});

export function queueStatus(): QueueStatus {
  return { processed: [...processed].reverse(), processedTotal, inFlight };
}
```

### types.ts
```ts
// Pure types shared between the server module (queue.server.ts) and the island.
// Components must import types from here, NOT from queue.server.ts: a type import
// from a side-effectful server module still drags that module into the SSR
// component bundle, instantiating its worker/state a second time.

export interface NotificationJob {
  user: string;
}

export interface ProcessedEntry {
  user: string;
  at: number;
  ms: number;
}

export interface QueueStatus {
  processed: ProcessedEntry[];
  processedTotal: number;
  inFlight: number;
}
```

### usernames.ts
```ts
const names = ['alice', 'bob', 'carol', 'dave', 'erin', 'frank', 'grace', 'heidi', 'ivan', 'judy', 'mallory', 'olivia', 'peggy', 'trent', 'victor', 'wendy'];

export function randomUsername(): string {
  return names[Math.floor(Math.random() * names.length)] ?? 'alice';
}
```

### routes.ts
```ts
import { Mochi, success, mochiEvents } from 'mochi-framework';
import type { MochiRouteValue, MochiQueueConfig } from 'mochi-framework';
import { notificationQueue, queueStatus, QUEUE_NAME } from './queue.server';
import { randomUsername } from './usernames';

// Mounted in the site's Mochi.serve({ queues }) call — see src/routes.ts.
export const queues: MochiQueueConfig[] = [notificationQueue];

export const routes: Record<string, MochiRouteValue> = {
  '/demos/queue': Mochi.page('./src/demos/queue/Queue.svelte', {
    // `suggestedUser` is generated server-side so SSR and hydration agree.
    serverProps: () => ({ initial: queueStatus(), suggestedUser: randomUsername() }),
    actions: {
      enqueue: async ({ formData }) => {
        // Free-text username is safe unsanitized: it's only ever rendered through
        // Svelte text interpolation (`{entry.user}`), which auto-escapes.
        const user = String(formData.get('username') ?? '')
          .trim()
          .slice(0, 64);
        await notificationQueue.add({ user: user || 'anonymous' });
        return success({ queued: user || 'anonymous' });
      },
    },
  }),
  '/demos/queue/events': Mochi.sse((stream) => {
    // Broadcast the shared snapshot on enqueue and on settle, so every client's
    // in-flight/processed counts move together — no per-client reconciliation.
    const push = (event: { queue: string }) => {
      if (event.queue === QUEUE_NAME) {
        stream.send(JSON.stringify(queueStatus()));
      }
    };
    mochiEvents.on('queue:added', push);
    mochiEvents.on('queue:completed', push);
    mochiEvents.on('queue:failed', push);
    stream.onClose(() => {
      mochiEvents.off('queue:added', push);
      mochiEvents.off('queue:completed', push);
      mochiEvents.off('queue:failed', push);
    });
  }),
};
```

### index.ts
```ts
import { Mochi, logger } from 'mochi-framework';
import { routes, queues } from './routes';

await Mochi.serve({
  port: 3333,
  development: process.env.MODE === 'development',
  routes,
  queues,
});

logger.info('Server running at http://localhost:3333');
```