@kazzle/app 0.1.693

package/templates/realtime-app/components/ui/src/styles/theme.css

@@ -0,0 +1,181 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ *  Kazzle app theme — the ONE styling entry point for this app.
+ *
+ *  This file is the design system. It is imported once (in `main.tsx`) and
+ *  gives you three things, in order:
+ *
+ *    1. Tailwind v4            — every utility class (`flex`, `gap-4`,
+ *                                `rounded-xl`, `text-zinc-500`, …) works in
+ *                                your JSX. No config file, no PostCSS setup.
+ *    2. Design tokens (@theme) — colors, radius, fonts as CSS variables. Edit
+ *                                these to re-skin the whole app at once.
+ *    3. Primitives (@layer)    — a few ready-made classes (`.btn`, `.card`,
+ *                                `.input`, `.field`, `.page`, `.stack`,
+ *                                `.row`) so common UI looks good with zero
+ *                                effort.
+ *
+ *  HOW TO STYLE — pick whichever is easier, mix freely:
+ *    • Tailwind utilities in `className` for one-off layout/spacing.
+ *    • A primitive class (`.btn`, `.card`) for the common building blocks.
+ *
+ *  WHY IT'S BUILT THIS WAY: styles live in the markup (utilities) or in named
+ *  primitives here — never in a separate per-screen stylesheet keyed to class
+ *  names you have to keep in sync. Rewriting a component can't silently strip
+ *  its styling, because the styling travels with the elements.
+ *
+ *  TO EXTEND: add new design tokens under `@theme`, and add new reusable
+ *  building blocks under `@layer components`. Keep app-specific one-offs as
+ *  inline Tailwind utilities in the component instead of adding a class here.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+@import "tailwindcss";
+
+/* ── Design tokens ──────────────────────────────────────────────────────────
+ * Exposed to Tailwind as `bg-surface`, `text-fg`, `text-muted`,
+ * `bg-accent`, `rounded-app`, etc. Change a value here and every utility and
+ * primitive that references it updates at once. */
+@theme {
+  --color-bg: #0b0f1a;
+  --color-surface: #131a2a;
+  --color-surface-raised: #1b2438;
+  --color-fg: #e8edf7;
+  --color-muted: #94a3b8;
+  --color-border: rgba(148, 163, 184, 0.18);
+  --color-accent: #6366f1;
+  --color-accent-hover: #4f46e5;
+  --color-accent-fg: #ffffff;
+  --color-danger: #f87171;
+
+  --radius-app: 0.875rem;
+
+  --font-sans: "Inter", ui-sans-serif, system-ui, -apple-system,
+    BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+
+/* ── Base ────────────────────────────────────────────────────────────────────
+ * Sensible document defaults so even unstyled markup reads well. */
+@layer base {
+  html,
+  body,
+  #root {
+    min-height: 100%;
+  }
+
+  body {
+    margin: 0;
+    background: var(--color-bg);
+    color: var(--color-fg);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+  }
+
+  h1 {
+    font-size: 1.875rem;
+    font-weight: 700;
+    letter-spacing: -0.02em;
+    margin: 0;
+  }
+
+  h2 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin: 0;
+  }
+}
+
+/* ── Primitives ──────────────────────────────────────────────────────────────
+ * Reusable building blocks. Use them directly (`<button class="btn btn-primary">`)
+ * or layer Tailwind utilities on top. Add new ones here when a pattern repeats. */
+@layer components {
+  /* Page wrapper — centers content with comfortable gutters. */
+  .page {
+    width: min(100% - 2rem, 48rem);
+    margin-inline: auto;
+    padding-block: 3rem;
+    display: flex;
+    flex-direction: column;
+    gap: 1.5rem;
+  }
+
+  /* Vertical / horizontal stacks. */
+  .stack {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+  }
+  .row {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+  }
+
+  /* Card surface. */
+  .card {
+    background: var(--color-surface);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-app);
+    padding: 1.25rem;
+  }
+
+  /* Buttons. `.btn` is the neutral base; add `.btn-primary` for the accent. */
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+    padding: 0.625rem 1rem;
+    border-radius: var(--radius-app);
+    border: 1px solid var(--color-border);
+    background: var(--color-surface-raised);
+    color: var(--color-fg);
+    font: inherit;
+    font-weight: 500;
+    cursor: pointer;
+    transition: background 0.15s, border-color 0.15s, opacity 0.15s;
+  }
+  .btn:hover {
+    background: color-mix(in srgb, var(--color-surface-raised) 80%, white);
+  }
+  .btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  .btn-primary {
+    background: var(--color-accent);
+    border-color: transparent;
+    color: var(--color-accent-fg);
+  }
+  .btn-primary:hover {
+    background: var(--color-accent-hover);
+  }
+
+  /* Text input / select. */
+  .input {
+    width: 100%;
+    min-width: 0;
+    padding: 0.625rem 0.875rem;
+    border-radius: var(--radius-app);
+    border: 1px solid var(--color-border);
+    background: var(--color-surface-raised);
+    color: var(--color-fg);
+    font: inherit;
+    outline: none;
+  }
+  .input:focus {
+    border-color: var(--color-accent);
+  }
+
+  /* Labelled field: <label class="field"><span>Label</span><input class="input"/></label> */
+  .field {
+    display: flex;
+    flex-direction: column;
+    gap: 0.375rem;
+    font-size: 0.875rem;
+    color: var(--color-muted);
+  }
+
+  /* Muted helper / secondary text. */
+  .muted {
+    color: var(--color-muted);
+  }
+}

package/templates/realtime-app/components/ui/src/vite-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="vite/client" />
+/// <reference types="vite-plugin-pwa/client" />

package/templates/realtime-app/components/ui/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/realtime-app/components/ui/vite.config.ts

@@ -0,0 +1,86 @@
+/**
+ * Vite config for the UI component.
+ *
+ * Kazzle preview/runtime wiring (HOST/PORT binding, strictPort, allowedHosts,
+ * backend proxy) lives in @kazzle/app/vite — the ONE shared place that must
+ * never be reinvented. This template declares a backend `server` component
+ * (PowerSync sync endpoint); we proxy `/sync` to it via the helper. Add new
+ * backend routes to `proxyPaths`.
+ *
+ * PWA + worker config below is realtime-specific (offline-first PowerSync) and
+ * stays here on top of the shared port contract.
+ */
+import { defineConfig, type Plugin } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import { VitePWA } from 'vite-plugin-pwa';
+import { kazzleAppVite } from '@kazzle/app/vite';
+
+/**
+ * Dev-only: any browser that previously visited a built/PWA-enabled version
+ * of this app at the same origin still has a service worker installed. With
+ * `devOptions.enabled: false` we don't serve a SW in dev, so the stale SW
+ * keeps intercepting requests with its old precache and the page renders
+ * without current CSS/JS. This plugin responds to /sw.js (and the PWA
+ * register helper) with a tiny script that unregisters every SW, clears all
+ * caches, and reloads the page once. Once cleaned, the SW is gone and Vite
+ * HMR works normally. Safe to keep enabled — production builds skip this
+ * plugin (the `serve` command guard).
+ */
+function devUnregisterServiceWorker(): Plugin {
+  const body = [
+    "self.addEventListener('install', e => self.skipWaiting());",
+    "self.addEventListener('activate', e => e.waitUntil((async () => {",
+    "  try { await self.registration.unregister(); } catch {}",
+    "  try { const keys = await caches.keys(); await Promise.all(keys.map(k => caches.delete(k))); } catch {}",
+    "  const clients = await self.clients.matchAll({ type: 'window' });",
+    "  for (const c of clients) { try { c.navigate(c.url); } catch {} }",
+    "})());",
+  ].join('\n');
+  return {
+    name: 'kazzle:dev-unregister-sw',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        if (req.method !== 'GET') return next();
+        const url = req.url?.split('?')[0];
+        if (url !== '/sw.js' && url !== '/registerSW.js') return next();
+        res.setHeader('content-type', 'application/javascript; charset=utf-8');
+        res.setHeader('cache-control', 'no-store');
+        res.end(body);
+      });
+    },
+  };
+}
+
+export default defineConfig(({ command }) => ({
+  plugins: [
+    react(),
+    tailwindcss(),
+    devUnregisterServiceWorker(),
+    // Service worker for offline-first behavior. `devOptions.enabled: false`
+    // is intentional — enabling the SW in dev breaks Vite HMR
+    // (templates.mdc note). The SW only ships in the production build, where
+    // it pre-caches the app shell + JS bundles so reload-while-offline keeps
+    // working. PowerSync's local SQLite stays readable in both modes.
+    VitePWA({
+      registerType: 'autoUpdate',
+      devOptions: { enabled: false },
+      workbox: { globPatterns: ['**/*.{js,css,html,svg,png,ico}'] },
+      manifest: {
+        name: 'Kazzle App',
+        short_name: 'Kazzle',
+        display: 'standalone',
+        start_url: '/',
+      },
+    }),
+  ],
+  // HOST/PORT/strictPort/allowedHosts + /sync proxy. See @kazzle/app/vite.
+  ...kazzleAppVite(command, { apiComponent: 'server', proxyPaths: ['/sync'] }),
+  optimizeDeps: {
+    exclude: ['@journeyapps/wa-sqlite', '@powersync/web'],
+  },
+  worker: {
+    format: 'es',
+  },
+}));

package/templates/realtime-app/kazzle.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from '@kazzle/app';
+
+export default defineConfig({
+  /** Path to the app icon relative to the repo root. Uploaded to CDN on publish. */
+  icon: 'components/ui/public/favicon.svg',
+  /** App components — each entry defines a deployable unit. Max 1 UI component. */
+  components: [
+    { name: 'ui', type: 'ui', path: './components/ui' },
+    { name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: 'bun run dev', run: 'bun run start' } },
+  ],
+});

package/templates/realtime-app/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{APP_SLUG}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "components/*"
+  ],
+  "scripts": {
+    "dev": "bun run --cwd components/ui dev",
+    "start": "bun run --cwd components/server start",
+    "check": "bun run --filter='./components/*' check"
+  },
+  "dependencies": {
+    "@kazzle/app": "{{KAZZLE_APP_VERSION}}"
+  }
+}

package/templates/shared/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="hsl(230,65%,88%)"/>
+  <text x="32" y="46" text-anchor="middle" font-family="system-ui,sans-serif" font-size="40" font-weight="600" fill="hsl(230,50%,25%)">K</text>
+</svg>

package/templates/ui-app/KAZZLE.md

@@ -0,0 +1,16 @@
+# Kazzle template context
+
+This app was created from the `ui` template. It is a frontend-only React and Vite app.
+
+Template-owned setup:
+- `kazzle.config.ts` declares one UI component.
+- `components/ui/package.json` already contains the Vite dev, build, typecheck, and check scripts.
+- `components/ui/src/main.tsx` and `components/ui/src/App.tsx` are the base UI entrypoint. `main.tsx` imports the design system once via `src/styles/theme.css`.
+
+Styling — this is mandatory, not a suggestion:
+- The design system is `src/styles/theme.css`. It already imports Tailwind v4 (`@import "tailwindcss"`) so EVERY Tailwind utility class works in `className`, plus ready-made primitives (`.page`, `.stack`, `.row`, `.card`, `.btn`, `.btn-primary`, `.input`, `.field`, `.muted`) and design tokens.
+- Style ONLY two ways: Tailwind utility classes in `className` (e.g. `className="flex items-center gap-4 rounded-xl"`), and/or the primitives above. Mix freely.
+- NEVER invent semantic class names (`app-shell`, `hero`, `stats-grid`, `listing-grid`, …) and NEVER add a separate per-screen stylesheet keyed to class names. Those classes have no CSS behind them, so the app renders with no layout. If a pattern repeats, add a primitive under `@layer components` in `theme.css` — do not create a new CSS file.
+- To re-skin, edit the `@theme` tokens in `theme.css`. Do not create `App.css` or any other stylesheet.
+
+Do not add a server component, database wiring, or secret env refs unless the user's requirements need backend behavior. For ordinary Postgres persistence, use the `ui-db` template instead of converting this app by hand.