create-kai 0.1.0

package/dist/templates/nextjs/app/components/Sidebar.tsx

@@ -0,0 +1,48 @@
+import { Conversations } from '@kitn.ai/ui/react';
+import type { Theme } from '../theme';
+import type { Conversation } from '../chat-data';
+
+interface SidebarProps {
+  theme: Theme;
+  conversations: Conversation[];
+  activeId: string;
+  collapsed: boolean;
+  onSelect: (id: string) => void;
+  onNewChat: () => void;
+  onToggle: () => void;
+}
+
+/**
+ * The conversation rail — a thin wrapper over `<kai-conversations>`.
+ *
+ * `conversations` is an ARRAY, so it crosses as a JS property rather than an HTML
+ * attribute. That is the half of the contract server rendering makes visible: the
+ * prerender emits `<kai-conversations></kai-conversations>` with no `conversations`
+ * attribute anywhere, because the wrapper assigns the property from a layout effect
+ * that only ever runs in the browser.
+ *
+ * NO `'use client'` HERE, and that is not an oversight. The directive marks the
+ * BOUNDARY, not every file past it: `app/workspace.tsx` carries it, so everything
+ * it imports is already in the client graph. Repeating it on each leaf would be
+ * harmless noise that teaches the wrong rule.
+ *
+ * The `.sidebar` div owns the shell's right border (kept OFF the element so it follows
+ * the shell's light/dark tokens, not the light-mode ones the element pins on itself at
+ * `:host`).
+ */
+export function Sidebar({ theme, conversations, activeId, collapsed, onSelect, onNewChat, onToggle }: SidebarProps) {
+  return (
+    <aside className="sidebar">
+      <Conversations
+        theme={theme}
+        groups={[]} /* flat list: the element buckets `conversations` by recency itself */
+        conversations={conversations}
+        activeId={activeId}
+        collapsed={collapsed}
+        onConversationSelect={(e) => onSelect(e.detail.id)}
+        onNewChat={onNewChat}
+        onToggleSidebar={onToggle}
+      />
+    </aside>
+  );
+}

package/dist/templates/nextjs/app/components/ThemeToggle.tsx

@@ -0,0 +1,27 @@
+import { Button } from '@kitn.ai/ui/react';
+import type { Theme } from '../theme';
+import { MoonIcon, SunIcon } from './icons';
+
+interface ThemeToggleProps {
+  theme: Theme;
+  onToggle: () => void;
+}
+
+/**
+ * Light/dark switch for the top bar. Shows the moon in light mode (tap → dark) and
+ * the sun in dark mode. The `<Button>` is icon-only, so it carries the accessible
+ * label; the glyph is decorative (`aria-hidden`) and sits in the `icon` slot.
+ *
+ * The glyph is chosen from `theme`, which is client state seeded to the same value
+ * on both sides of hydration — NOT from `prefers-color-scheme`, which the server
+ * cannot read and which would therefore prerender a different icon than the client
+ * builds on hydration.
+ */
+export function ThemeToggle({ theme, onToggle }: ThemeToggleProps) {
+  const Glyph = theme === 'light' ? MoonIcon : SunIcon;
+  return (
+    <Button theme={theme} variant="ghost" size="icon" label="Toggle light/dark theme" onClick={onToggle}>
+      <Glyph slot="icon" aria-hidden />
+    </Button>
+  );
+}

package/dist/templates/nextjs/app/components/ThreadView.tsx

@@ -0,0 +1,48 @@
+import { Thread } from '@kitn.ai/ui/react';
+import type { ChatMessage } from '@kitn.ai/ui/react';
+import { partsToText } from '@kitn.ai/ui/state';
+import type { Theme } from '../theme';
+
+interface ThreadViewProps {
+  theme: Theme;
+  messages: ChatMessage[];
+}
+
+/**
+ * The scrolling message list, and the piece that carries the server-rendering
+ * proof.
+ *
+ * `<kai-thread>` (React `<Thread>`) owns the message rendering, the centered
+ * fixed-width column and stick-to-bottom scroll. The server emits it as an EMPTY
+ * tag — no `messages` attribute, no serialized thread — and the array only arrives
+ * once the wrapper's layout effect assigns `el.messages` in the browser. Streaming
+ * is that same channel repeated: a NEW array reference per chunk, which is why
+ * mutating the existing array in place would render nothing.
+ *
+ * This component just bakes the per-message actions onto the assistant turns and
+ * wires the custom `speak` action to the browser's speech synthesis. `copy` (and
+ * the feedback votes) are handled inside the element.
+ */
+export function ThreadView({ theme, messages }: ThreadViewProps) {
+  // <Thread> reads `actions` off each message; only assistant replies get them.
+  const withActions: ChatMessage[] = messages.map((m) =>
+    m.role === 'assistant'
+      ? { ...m, actions: ['copy', { id: 'speak', label: 'Read aloud', icon: 'volume-2' }] }
+      : m,
+  );
+  return (
+    <Thread
+      className="thread"
+      theme={theme}
+      messages={withActions}
+      onMessageAction={(e) => {
+        if (e.detail.action === 'speak') {
+          const m = messages.find((x) => x.id === e.detail.messageId);
+          if (!m) return;
+          window.speechSynthesis.cancel();
+          window.speechSynthesis.speak(new SpeechSynthesisUtterance(partsToText(m.parts)));
+        }
+      }}
+    />
+  );
+}

package/dist/templates/nextjs/app/components/icons/MoonIcon.tsx

@@ -0,0 +1,25 @@
+import type { SVGProps } from 'react';
+
+/**
+ * Moon glyph — shown in light mode (tap the toggle → dark). moon/sun aren't in the
+ * kit's `<Icon>` set, so the example owns them. Props spread straight onto the
+ * `<svg>`, so `slot="icon"`, `className`, and `aria-hidden` pass through and it
+ * drops into `<Button>`'s icon slot.
+ */
+export function MoonIcon({ size = 20, ...props }: { size?: number } & SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      width={size}
+      height={size}
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" />
+    </svg>
+  );
+}

package/dist/templates/nextjs/app/components/icons/SunIcon.tsx

@@ -0,0 +1,25 @@
+import type { SVGProps } from 'react';
+
+/**
+ * Sun glyph — shown in dark mode (tap the toggle → light). See `MoonIcon` for why
+ * the example owns these icons. Props spread straight onto the `<svg>`.
+ */
+export function SunIcon({ size = 20, ...props }: { size?: number } & SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      width={size}
+      height={size}
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2" /><path d="M12 20v2" /><path d="m4.93 4.93 1.41 1.41" /><path d="m17.66 17.66 1.41 1.41" />
+      <path d="M2 12h2" /><path d="M20 12h2" /><path d="m6.34 17.66-1.41 1.41" /><path d="m19.07 4.93-1.41 1.41" />
+    </svg>
+  );
+}

package/dist/templates/nextjs/app/components/icons/index.ts

@@ -0,0 +1,2 @@
+export { MoonIcon } from './MoonIcon';
+export { SunIcon } from './SunIcon';

package/dist/templates/nextjs/app/globals.css

@@ -0,0 +1,153 @@
+/* The app shell. Colors come from the kit's `--color-*` tokens, imported in
+   `app/layout.tsx` as `@kitn.ai/ui/theme.tokens.css`.
+
+   READ THE TOKEN IMPORT NOTE IN `layout.tsx` BEFORE CHANGING IT. The tokens have
+   to be the COMPILED stylesheet, not `@kitn.ai/ui/theme.css` — that one is
+   Tailwind v4 source, this app runs no Tailwind, and the `.app` rule below would
+   silently fall back to a transparent background in light mode with a completely
+   green build. The rules that sit INSIDE a kai-* element (`.sidebar`, `.bar`)
+   would survive it, which is what makes the failure hard to see. */
+
+html,
+body {
+  height: 100%;
+  margin: 0;
+  font-family: system-ui, -apple-system, sans-serif;
+  background: var(--color-background);
+  color: var(--color-foreground);
+}
+
+/* Full-height workspace shell. `.dark` is toggled on THIS element rather than on
+   <html>, which is what keeps the theme out of the prerendered document: the theme
+   is client state, so the server and the first client render agree on it and there
+   is nothing for hydration to disagree about. <kai-resizable> fills this box (its
+   `:host` is `height:100%`) and owns the sidebar | main split. */
+.app {
+  height: 100dvh;
+  background: var(--color-background);
+  color: var(--color-foreground);
+}
+
+/* The sidebar is its own surface: `--color-muted` sits a step off
+   `--color-background` in both themes. That step is subtle in light mode, so a 1px
+   right border marks the at-rest division — <kai-resizable>'s `line` handle is
+   transparent until hover/drag, so the boundary has to come from the panel itself.
+   `box-sizing: border-box` keeps the border inside the 280px item so it doesn't
+   shift the content width. */
+.sidebar {
+  background: var(--color-muted);
+  border-right: 1px solid var(--color-border);
+  box-sizing: border-box;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.sidebar > * {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.main {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  height: 100%;
+}
+
+.bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.bar-left,
+.bar-right {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-width: 0;
+}
+
+.brand {
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: var(--color-muted-foreground);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* The hydration badge (see app/components/HydrationBadge.tsx). Two states, and the
+   colours are the point: prerendered HTML shows the neutral one, and it only goes
+   green once a client effect has run. */
+.hydration {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+  padding: 0.2rem 0.5rem;
+  border-radius: 999px;
+  border: 1px solid var(--color-border);
+  background: var(--color-muted);
+  color: var(--color-muted-foreground);
+  white-space: nowrap;
+}
+
+.hydration[data-state='hydrated'] {
+  color: var(--color-foreground);
+}
+
+.hydration-dot {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: 50%;
+  background: var(--color-muted-foreground);
+}
+
+.hydration[data-state='hydrated'] .hydration-dot {
+  background: #22c55e;
+}
+
+/* <kai-thread> scrolls internally and centers its own fixed-width column, so the
+   host just needs to fill the remaining height of the main flex column. */
+.thread {
+  flex: 1;
+  min-height: 0;
+}
+
+/* No top divider above the input — the composer floats against the thread. Extra
+   bottom padding lifts the input + hint off the viewport edge. */
+.composer {
+  padding: 0.75rem 1rem 1.5rem;
+}
+
+/* Match the composer to the centered message column above it. */
+.composer > * {
+  display: block;
+  width: 100%;
+  max-width: 48rem;
+  margin: 0 auto;
+}
+
+.composer-hint {
+  margin: 0.5rem auto 0;
+  font-size: 0.75rem;
+  text-align: center;
+  color: var(--color-muted-foreground);
+}
+
+.composer-hint kbd {
+  font-family: inherit;
+  font-size: 0.6875rem;
+  padding: 0.05rem 0.3rem;
+  border-radius: 0.25rem;
+  border: 1px solid var(--color-border);
+  background: var(--color-muted);
+  color: var(--color-foreground);
+}

package/dist/templates/nextjs/app/hooks/index.ts

@@ -0,0 +1 @@
+export { useConversations } from './useConversations';

package/dist/templates/nextjs/app/hooks/useConversations.ts

@@ -0,0 +1,42 @@
+import { useCallback, useState } from 'react';
+import type { KaiChatController } from '@kitn.ai/ui/react';
+import { THREADS, newId, type Conversation } from '../chat-data';
+
+/**
+ * Owns the conversation list + which one is active, plus the in-memory `THREADS`
+ * stash: on select/new we swap the OPEN thread out to `THREADS` and swap the
+ * picked one in. Takes the `useKaiChat` controller so it can read the live
+ * messages when stashing and reset them when loading another thread.
+ *
+ * In-memory on purpose — this is where a real app would read and write a database
+ * from a Next server action or a route handler. Nothing here runs on the server:
+ * the hook's initial state is the same on both sides of hydration, and every
+ * mutation is driven by a user event.
+ */
+export function useConversations(chat: KaiChatController, initial: Conversation[]) {
+  const [conversations, setConversations] = useState<Conversation[]>(initial);
+  const [activeId, setActiveId] = useState(initial[0].id);
+
+  const selectConversation = useCallback(
+    (id: string) => {
+      THREADS[activeId] = chat.messages; // stash the open thread
+      setActiveId(id);
+      chat.setMessages(THREADS[id] ?? []); // load the picked one
+    },
+    [activeId, chat],
+  );
+
+  const newChat = useCallback(() => {
+    const id = newId();
+    THREADS[activeId] = chat.messages;
+    THREADS[id] = [];
+    setConversations((cs) => [
+      { id, title: 'New conversation', scope: { type: 'collection' }, messageCount: 0, lastMessageAt: new Date().toISOString(), updatedAt: new Date().toISOString() },
+      ...cs,
+    ]);
+    setActiveId(id);
+    chat.setMessages([]);
+  }, [activeId, chat]);
+
+  return { conversations, activeId, selectConversation, newChat };
+}

package/dist/templates/nextjs/app/layout.tsx

@@ -0,0 +1,50 @@
+// Root layout — a React Server Component (no 'use client' here).
+//
+// The kit's design tokens, as PLAIN COMPILED CSS.
+//
+// IT MUST BE `theme.tokens.css`, NOT `theme.css`. They are not two spellings of
+// one file: `@kitn.ai/ui/theme.css` is Tailwind v4 SOURCE — its light tokens live
+// inside an `@theme { … }` block, which is a Tailwind at-rule, not CSS. This app
+// runs no Tailwind (`postcss.config.mjs` declares no plugins), so that file would
+// reach the browser verbatim, where an unknown at-rule is DISCARDED WHOLE, and
+// `next build` would stay green throughout. That is what this starter shipped
+// until it was measured on the emitted asset: `.next/static/css/*.css` carried
+// one raw `@theme {`, and `--color-background` was defined nowhere else.
+//
+// WHAT THAT ACTUALLY BREAKS, stated at its real size, because "the app renders on
+// fallbacks" is the easy version and it is wrong. Dark mode is fine — those tokens
+// are a plain `.dark` rule. In light mode `:root` defines no `--color-*` at all,
+// but anything nested inside a `kai-*` element still resolves — nothing re-scopes
+// anything: Tailwind emits `@theme` to `:root, :host`, so the elements' own
+// compiled CSS pins the tokens on every host and children inherit off it, slotted
+// or not. What loses its colours is the chrome OUTSIDE every element — this app's
+// `.app` shell and `html`/`body`, measured computing
+// `background-color: rgba(0, 0, 0, 0)`. Theming host-page chrome is exactly what
+// this stylesheet is for, and the narrowness is why the bug survived: the page
+// looks nearly right.
+//
+// THE RULE IS "DOES TAILWIND PROCESS THIS FILE", NOT "NEVER IMPORT theme.css".
+// The Solid starter imports the very same `theme.css` and is correct, because its
+// stylesheet says `@import "tailwindcss"` above it and `@tailwindcss/vite` is in
+// the pipeline, so `@theme` is COMPILED rather than discarded. Add Tailwind here
+// and you would switch back.
+//
+// A CSS import works from a Server Component because it has no client runtime,
+// and importing it HERE is what puts the stylesheet in the prerendered document,
+// so there is no flash of unstyled custom elements.
+import '@kitn.ai/ui/theme.tokens.css';
+import './globals.css';
+import type { ReactNode } from 'react';
+
+export const metadata = {
+  title: '@kitn.ai/ui — Next.js App Router example',
+  description: 'A chat workspace composed by hand from the kai-* web components, on Next.js 15 / React 19.',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/dist/templates/nextjs/app/page.tsx

@@ -0,0 +1,17 @@
+// This page is a React Server Component (NO 'use client' here) — the App Router
+// default, and the shape the kit is meant to be consumed in.
+//
+// The chat workspace itself is the client island next door, `app/workspace.tsx`.
+// It carries the directive because IT uses hooks and event-handler props — the
+// standard RSC rule. Rendering a kai wrapper does NOT need one: the wrappers in
+// `@kitn.ai/ui/react` ship their own `'use client'` banner, so they are already
+// client components and a Server Component can render them like any other.
+//
+// So the whole page still prerenders on the server: this component runs there,
+// the island is prerendered to HTML there too, and the browser gets a document
+// with bare `<kai-*>` tags in it. `app/workspace.tsx` explains what that proves.
+import { Workspace } from './workspace';
+
+export default function HomePage() {
+  return <Workspace />;
+}

package/dist/templates/nextjs/app/theme.ts

@@ -0,0 +1,10 @@
+/**
+ * The shell's color mode.
+ *
+ * Its own module rather than an export from `workspace.tsx`. That file carries
+ * `'use client'`, and a Server Component importing a type back out of it would
+ * point the dependency the wrong way round — types erase, so it would compile,
+ * but the import graph would say the server depends on a client module. Anything
+ * shared between the two sides lives in a file that declares neither.
+ */
+export type Theme = 'light' | 'dark';

package/dist/templates/nextjs/app/workspace.tsx

@@ -0,0 +1,148 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { Button, Resizable, ResizableItem, useKaiChat } from '@kitn.ai/ui/react';
+import { readOpenAIStream } from '@kitn.ai/ui/wire';
+import { CONVERSATIONS, THREADS, SUGGESTIONS, TRIGGERS, newId, mockResponse } from './chat-data';
+import { Sidebar } from './components/Sidebar';
+import { ThreadView } from './components/ThreadView';
+import { Composer } from './components/Composer';
+import { ThemeToggle } from './components/ThemeToggle';
+import { HydrationBadge } from './components/HydrationBadge';
+import { useConversations } from './hooks';
+import type { Theme } from './theme';
+
+/**
+ * A mini chat **workspace composed by hand** from @kitn.ai/ui's individual
+ * elements — prerendered by the App Router, then hydrated and streamed into.
+ *
+ *   <Resizable>/<ResizableItem>  — the draggable sidebar | main split
+ *   <Conversations>  — the sidebar list (fed `conversations`, emits select/new)
+ *   <Thread>         — the scrolling message list (kai-thread; stick-to-bottom built in)
+ *   <PromptInput>    — the composer at the bottom
+ *
+ * `useKaiChat` owns the message array + streaming; everything else is plain React
+ * state. Swap `mockResponse(text)` for a real `fetch` to ship a real app.
+ *
+ * WHY THE `'use client'` IS ON THIS FILE AND NOT ON app/page.tsx
+ * -------------------------------------------------------------
+ * It is here because THIS component uses hooks and passes event handlers, which is
+ * the standard React Server Component rule — NOT a requirement of the kit. The
+ * `@kitn.ai/ui/react` wrappers ship their own `'use client'` banner, so a Server
+ * Component can render one directly with no directive of its own; `app/page.tsx`
+ * stays a Server Component and simply renders this island. The directive marks a
+ * boundary, so everything imported below is already in the client graph and none
+ * of those files repeats it.
+ *
+ * WHAT THIS PAGE PROVES ABOUT SERVER RENDERING
+ * --------------------------------------------
+ * This starter exists to show that the `kai-*` web components survive SSR/RSC. It
+ * used to show that with a `<Button>` rendered from a Server Component and a
+ * static `<Conversations>` fed a frozen array. A composed thread that hydrates and
+ * then STREAMS proves strictly more, so the demonstration moved here rather than
+ * being kept alongside — `create-kai` copies this whole starter into every
+ * scaffolded project, so a second demo route would be dead code in each one:
+ *
+ *   1. The server emits BARE TAGS. `@kitn.ai/ui/react` registers each element from
+ *      a layout effect, and layout effects do not run during a prerender, so the
+ *      HTML Next ships contains `<kai-thread></kai-thread>` and nothing inside it.
+ *      View source and you will find empty elements — that is correct, not a bug.
+ *   2. Array and object props NEVER become attributes. `messages`, `conversations`
+ *      and `triggers` are assigned as live DOM properties after hydration, so
+ *      there is no serialize/parse step and no `messages="[{...}]"` in the markup.
+ *      The static version proved this ONCE, at mount.
+ *   3. Streaming proves the channel KEEPS working. Every chunk assigns a new
+ *      `messages` array reference to the same element the server rendered empty. A
+ *      page that hydrated badly can still look right; it cannot stream. The badge
+ *      in the top bar reports which of those you are looking at — and on Next that
+ *      badge earns its keep twice over, because a PRODUCTION React build minifies
+ *      hydration errors into a numbered link. Run `next dev` when you want them in
+ *      words.
+ *
+ * Nothing on this page is fetched from the server: no server action, no route
+ * handler, no `fetch` in a Server Component. The reply comes from the kit's mock
+ * responder in the browser. That keeps the SSR question — does the ELEMENT survive
+ * hydration — separate from a data-loading question this starter is not about.
+ */
+export function Workspace() {
+  const [theme, setTheme] = useState<Theme>('dark');
+  const [collapsed, setCollapsed] = useState(false);
+  const chat = useKaiChat({ initialMessages: THREADS[CONVERSATIONS[0].id] ?? [] });
+  const { conversations, activeId, selectConversation, newChat } = useConversations(chat, CONVERSATIONS);
+
+  const send = useCallback(
+    async (raw: string) => {
+      const text = raw.trim();
+      if (!text) return;
+      // The Composer already cleared its own input; here we just append the user
+      // message and stream the (mock) assistant reply.
+      chat.append({ id: newId(), role: 'user', parts: [{ type: 'text', text }] });
+      const stream = chat.streamAssistant();
+      // NO BACKEND AND NO PROVIDER. mockResponse() yields canned SSE frames that
+      // go through the SAME reader a real model's response would, so this preview
+      // exercises the real path. To go live, only this one expression changes —
+      // `mockResponse(text)` becomes a POST to a Next route handler
+      // (`app/api/chat/route.ts`), with toOpenAIMessages(chat.messages) as the
+      // body. The line below stays.
+      await readOpenAIStream(mockResponse(text), stream);
+      stream.done();
+    },
+    [chat],
+  );
+
+  return (
+    <div className={`app${theme === 'dark' ? ' dark' : ''}`}>
+      {/* <kai-resizable> owns the sidebar width + the divider. The handle defaults
+          to the `line` hairline (transparent at rest, tinting on hover/drag);
+          collapsing the sidebar maps to <ResizableItem collapsed>. */}
+      <Resizable theme={theme} orientation="horizontal">
+        <ResizableItem theme={theme} size="280px" min="220px" max="420px" collapsed={collapsed}>
+          <Sidebar
+            theme={theme}
+            conversations={conversations}
+            activeId={activeId}
+            collapsed={collapsed}
+            onSelect={selectConversation}
+            onNewChat={newChat}
+            onToggle={() => setCollapsed((c) => !c)}
+          />
+        </ResizableItem>
+
+        <ResizableItem theme={theme}>
+          <main className="main">
+            <header className="bar">
+              <div className="bar-left">
+                {collapsed && (
+                  <Button
+                    theme={theme}
+                    variant="ghost"
+                    size="icon"
+                    icon="panel-left"
+                    label="Show sidebar"
+                    onClick={() => setCollapsed(false)}
+                  />
+                )}
+                <span className="brand">@kitn.ai/ui · composed chat on Next.js</span>
+              </div>
+              <div className="bar-right">
+                <HydrationBadge />
+                <ThemeToggle theme={theme} onToggle={() => setTheme((t) => (t === 'light' ? 'dark' : 'light'))} />
+              </div>
+            </header>
+
+            <ThreadView theme={theme} messages={chat.messages} />
+
+            <Composer
+              theme={theme}
+              loading={chat.loading}
+              suggestions={chat.messages.length <= 2 ? SUGGESTIONS : []}
+              triggers={TRIGGERS}
+              onSubmit={send}
+              onSuggestionClick={send}
+            />
+          </main>
+        </ResizableItem>
+      </Resizable>
+    </div>
+  );
+}

package/dist/templates/nextjs/next.config.mjs

@@ -0,0 +1,22 @@
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // No special config is required to consume @kitn.ai/ui in a STANDALONE app:
+  // - It ships pre-compiled ESM in `dist/`, so `transpilePackages` is NOT needed.
+  // - The register-all entry (`@kitn.ai/ui/elements`) is SSR-safe — it touches
+  //   no `window`/`customElements` at import time, so importing it never throws
+  //   during server rendering; it only registers in the browser.
+  //
+  // `outputFileTracingRoot` is only here because this example is NESTED inside
+  // the library's monorepo: it pins the workspace root so Next doesn't walk up
+  // and inherit the repo root's lockfile / Tailwind PostCSS config. A standalone
+  // app does not need this (nor the local postcss.config.mjs).
+  outputFileTracingRoot: __dirname,
+  reactStrictMode: true,
+};
+
+export default nextConfig;

package/dist/templates/nextjs/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@kitn.ai/ui-example-nextjs",
+  "private": true,
+  "version": "0.0.0",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@kitn.ai/ui": "file:../../../packages/ui",
+    "next": "^15.5.19",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.3"
+  }
+}