@press2ai/engine 0.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@press2ai/engine",
+  "version": "0.1.0",
+  "description": "Multi-tenant runtime + template contracts dla otwarty-* verticali. SSR na Cloudflare Workers, isomorphic renderer (SSG/browser w roadmapie).",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./template-trener": "./src/template-trener.ts",
+    "./template-blog": "./src/template-blog.ts",
+    "./types": "./src/types.ts"
+  },
+  "scripts": {
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}

package/src/engine-signature.ts

@@ -0,0 +1,43 @@
+/**
+ * Engine signatures — pozostałe TRZY tryby wykonania (SSG + Browser).
+ * SSR zostało wyciągnięte do runtime/ssr.ts (ma już prawdziwą implementację).
+ * Te dwa pozostają jako `declare` do czasu implementacji w runtime/.
+ */
+
+import type { OtwartyTemplate, BuildFile, RenderResult } from './types';
+
+/* ─────────────── Faza 1: SSG build do plików statycznych ─────────────── */
+
+export interface SSGBuildOpts<C, T> {
+  template: OtwartyTemplate<C, T>;
+  theme: T;
+  /** Treść jest stała na czas builda — z disku, z migracji z Faza 0, z CMS. */
+  content: C;
+  baseUrl: string;
+  /** Output adapter — pisanie plików, upload do CF Pages, push do Codeberg Pages. */
+  output: SSGOutput;
+}
+
+export interface SSGOutput {
+  write(file: BuildFile): Promise<void>;
+  finalize?(): Promise<void>;
+}
+
+export declare function createSSGBuild<C, T>(opts: SSGBuildOpts<C, T>): Promise<{ files: BuildFile[] }>;
+
+/* ─────────────── Browser: live preview w lokalnym edytorze ─────────────── */
+
+export interface BrowserRendererOpts<C, T> {
+  template: OtwartyTemplate<C, T>;
+  theme: T;
+  baseUrl: string;
+}
+
+export interface BrowserRenderer<C> {
+  /** Renderuje konkretną ścieżkę dla aktualnej treści — używane przez iframe preview. */
+  preview(content: C, path: string): RenderResult;
+  /** Lista wszystkich ścieżek wyliczonych z treści — używane przez side panel "Strony". */
+  listRoutes(content: C): string[];
+}
+
+export declare function createBrowserRenderer<C, T>(opts: BrowserRendererOpts<C, T>): BrowserRenderer<C>;

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @press2ai/engine — public exports.
+ */
+
+// Types — kontrakty templatów
+export type {
+  OtwartyTemplate,
+  PresenceTemplate,
+  CommerceTemplate,
+  RouteDescriptor,
+  RenderRequest,
+  RenderContext,
+  RenderResult,
+  HeadMeta,
+  EditorSchema,
+  EditorField,
+  EditorSection,
+  DataSource,
+  DataSourceInput,
+  SitemapEntry,
+  RssFeed,
+  RssItem,
+  CommerceProviders,
+  PaymentProviderId,
+  ShippingProviderId,
+  InvoiceProviderId,
+  ProviderSlot,
+  BuildFile,
+  TemplateMeta,
+} from './types';
+
+// Runtime — Faza 0 SSR multi-tenant
+export { createSSRWorker, type SSRWorkerOpts, type OtwartyWorker } from './runtime/ssr';

package/src/runtime/ssr.ts

@@ -0,0 +1,232 @@
+/**
+ * createSSRWorker — Faza 0 multi-tenant runtime na CF Worker.
+ *
+ * Bierze OtwartyTemplate + theme + content loader. Per request:
+ *   1. Parsuje URL → host, path, query
+ *   2. Obsługuje wbudowane endpointy: /sitemap.xml, /robots.txt, /feed.xml
+ *   3. Ładuje content przez loadContent(host, env) — multi-tenancy hook
+ *   4. Matchuje path do template.routes() → wyciąga params
+ *   5. Wywołuje template.render(req, ctx) — czystą funkcję
+ *   6. Zwraca Response z body + nagłówkami z RenderResult
+ *
+ * Mutacje (POST/PUT/DELETE) NIE należą do engine v0.1 — landing wrapper
+ * trzyma własne handlery dla opt-out, claim, edycji. Engine jest GET-only.
+ */
+
+import type {
+  OtwartyTemplate,
+  RouteDescriptor,
+  RenderRequest,
+  RenderContext,
+  SitemapEntry,
+  RssFeed,
+} from '../types';
+
+export interface SSRWorkerOpts<C, T> {
+  template: OtwartyTemplate<C, T>;
+  theme: T;
+  /** Resolver host → tenant content. Engine cache'uje po stronie KV jeśli podany. */
+  loadContent(host: string, env: unknown): Promise<C | null>;
+  /** Override base URL (np. dla preview albo custom domains). */
+  baseUrlFor?(host: string): string;
+}
+
+export interface OtwartyWorker {
+  fetch(request: Request, env: unknown, ctx?: unknown): Promise<Response>;
+}
+
+export function createSSRWorker<C, T>(opts: SSRWorkerOpts<C, T>): OtwartyWorker {
+  return {
+    async fetch(request, env): Promise<Response> {
+      // Engine obsługuje wyłącznie GET; mutacje są poza zakresem.
+      if (request.method !== 'GET' && request.method !== 'HEAD') {
+        return new Response('Method not allowed', { status: 405 });
+      }
+
+      const url = new URL(request.url);
+      const host = url.host;
+      const baseUrl = opts.baseUrlFor?.(host) ?? `${url.protocol}//${host}`;
+
+      // Wbudowane endpointy obsługiwane przez engine bezpośrednio
+      // (nie wymagają pełnego renderera, biorą dane z metod templatu).
+      if (url.pathname === '/sitemap.xml') {
+        return handleSitemap(opts, host, env, baseUrl);
+      }
+      if (url.pathname === '/robots.txt') {
+        return handleRobots(opts, host, env);
+      }
+      if (url.pathname === '/feed.xml' || url.pathname === '/rss.xml') {
+        return handleFeed(opts, host, env, baseUrl);
+      }
+
+      // Standard render path
+      const content = await opts.loadContent(host, env);
+      if (content === null) {
+        return new Response('Not found', { status: 404 });
+      }
+
+      const routes = opts.template.routes(content);
+      const match = matchRoute(url.pathname, routes);
+      if (!match) {
+        return new Response('Not found', { status: 404 });
+      }
+
+      const query: Record<string, string> = {};
+      url.searchParams.forEach((v, k) => { query[k] = v; });
+
+      const req: RenderRequest<C> = {
+        path: url.pathname,
+        params: match.params,
+        query,
+        content,
+      };
+
+      const ctx: RenderContext<T> = {
+        baseUrl,
+        theme: opts.theme,
+        locale: opts.template.meta.locale,
+        mode: 'ssr',
+      };
+
+      const result = opts.template.render(req, ctx);
+
+      const headers: Record<string, string> = {
+        'content-type': 'text/html; charset=utf-8',
+      };
+      // Cache-Control z route descriptor (jeśli podany) — pozwala CDN cachować
+      if (match.route.cacheControl) {
+        headers['cache-control'] = match.route.cacheControl;
+      }
+      // Nagłówki z RenderResult przesłaniają wszystko (template wie najlepiej)
+      Object.assign(headers, result.headers ?? {});
+
+      return new Response(result.body, {
+        status: result.status ?? 200,
+        headers,
+      });
+    },
+  };
+}
+
+/* ─────────────── Wbudowane endpointy ─────────────── */
+
+async function handleSitemap<C, T>(
+  opts: SSRWorkerOpts<C, T>,
+  host: string,
+  env: unknown,
+  baseUrl: string,
+): Promise<Response> {
+  const content = await opts.loadContent(host, env);
+  if (content === null) return new Response('Not found', { status: 404 });
+  const entries = opts.template.sitemap(content, baseUrl);
+  return new Response(renderSitemapXml(entries), {
+    headers: {
+      'content-type': 'application/xml; charset=utf-8',
+      'cache-control': 'public, s-maxage=86400',
+    },
+  });
+}
+
+async function handleRobots<C, T>(
+  opts: SSRWorkerOpts<C, T>,
+  host: string,
+  env: unknown,
+): Promise<Response> {
+  if (!opts.template.robots) {
+    return new Response('User-agent: *\nAllow: /\n', { headers: { 'content-type': 'text/plain' } });
+  }
+  const content = await opts.loadContent(host, env);
+  if (content === null) return new Response('Not found', { status: 404 });
+  return new Response(opts.template.robots(content), {
+    headers: { 'content-type': 'text/plain; charset=utf-8' },
+  });
+}
+
+async function handleFeed<C, T>(
+  opts: SSRWorkerOpts<C, T>,
+  host: string,
+  env: unknown,
+  baseUrl: string,
+): Promise<Response> {
+  if (!opts.template.feed) return new Response('Not found', { status: 404 });
+  const content = await opts.loadContent(host, env);
+  if (content === null) return new Response('Not found', { status: 404 });
+  const feed = opts.template.feed(content, baseUrl);
+  if (!feed) return new Response('Not found', { status: 404 });
+  return new Response(renderRssXml(feed), {
+    headers: {
+      'content-type': 'application/rss+xml; charset=utf-8',
+      'cache-control': 'public, s-maxage=3600',
+    },
+  });
+}
+
+/* ─────────────── Routing ─────────────── */
+
+interface RouteMatch<C> {
+  route: RouteDescriptor<C>;
+  params: Record<string, string>;
+}
+
+function matchRoute<C>(pathname: string, routes: RouteDescriptor<C>[]): RouteMatch<C> | null {
+  // Statyczne routes (bez :param) mają wyższy priorytet niż dynamiczne.
+  // Bez tego /sitemap.xml byłoby przechwycone przez /:slug.
+  const sorted = [...routes].sort((a, b) => {
+    const aDyn = a.path.includes(':');
+    const bDyn = b.path.includes(':');
+    if (aDyn === bDyn) return 0;
+    return aDyn ? 1 : -1;
+  });
+  for (const route of sorted) {
+    const params = matchPath(pathname, route.path);
+    if (params) return { route, params };
+  }
+  return null;
+}
+
+function matchPath(pathname: string, pattern: string): Record<string, string> | null {
+  const patternParts = pattern.split('/').filter(Boolean);
+  const pathParts = pathname.split('/').filter(Boolean);
+  if (patternParts.length !== pathParts.length) return null;
+
+  const params: Record<string, string> = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    const pp = patternParts[i]!;
+    const ap = pathParts[i]!;
+    if (pp.startsWith(':')) {
+      params[pp.slice(1)] = decodeURIComponent(ap);
+    } else if (pp !== ap) {
+      return null;
+    }
+  }
+  return params;
+}
+
+/* ─────────────── XML helpers ─────────────── */
+
+function renderSitemapXml(entries: SitemapEntry[]): string {
+  const items = entries
+    .map((e) => {
+      const lastmod = e.lastmod ? `<lastmod>${e.lastmod}</lastmod>` : '';
+      const changefreq = e.changefreq ? `<changefreq>${e.changefreq}</changefreq>` : '';
+      const priority = e.priority !== undefined ? `<priority>${e.priority}</priority>` : '';
+      return `  <url><loc>${escapeXml(e.loc)}</loc>${lastmod}${changefreq}${priority}</url>`;
+    })
+    .join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${items}\n</urlset>`;
+}
+
+function renderRssXml(feed: RssFeed): string {
+  const items = feed.items
+    .map((i) => {
+      const desc = i.description ? `<description>${escapeXml(i.description)}</description>` : '';
+      const ce = i.content ? `<content:encoded><![CDATA[${i.content}]]></content:encoded>` : '';
+      return `<item><title>${escapeXml(i.title)}</title><link>${escapeXml(i.link)}</link><guid>${escapeXml(i.guid)}</guid><pubDate>${i.pubDate}</pubDate>${desc}${ce}</item>`;
+    })
+    .join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">\n<channel>\n<title>${escapeXml(feed.title)}</title>\n<link>${escapeXml(feed.link)}</link>\n<description>${escapeXml(feed.description)}</description>\n${items}\n</channel>\n</rss>`;
+}
+
+function escapeXml(s: string): string {
+  return s.replace(/[<>&"']/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' })[c]!);
+}

package/src/template-blog.ts

@@ -0,0 +1,132 @@
+/**
+ * template-blog — drugi referencyjny PresenceTemplate.
+ * Jego ROLĄ jest udowodnić że abstrakcja przeżywa radikalnie inny kształt
+ * niż katalog wizytówek: enumeracja postów per :slug, RSS feed, brak
+ * data sources (treść w pełni manualna). Render jest minimalistyczny —
+ * theme contract zostawiamy płytki, bo blog może działać na dowolnym
+ * theme który ma `layout` + funkcję renderującą markdown body.
+ */
+
+import { z } from 'zod';
+import type { PresenceTemplate, RenderRequest, RenderContext, RenderResult, RssFeed } from './types';
+
+export interface BlogTheme {
+  layout(props: { title: string; description?: string; jsonLd?: object }, body: string): string;
+  /** Zamienia markdown na HTML — implementacja po stronie theme. */
+  markdown(md: string): string;
+  esc(s: string): string;
+}
+
+const postSchema = z.object({
+  slug: z.string(),
+  title: z.string(),
+  pubDate: z.string(), // ISO 8601
+  author: z.string().optional(),
+  excerpt: z.string().optional(),
+  body: z.string(), // markdown
+});
+
+const blogContentSchema = z.object({
+  brand: z.object({ siteName: z.string(), description: z.string(), authorEmail: z.string().email().optional() }),
+  posts: z.array(postSchema).default([]),
+});
+
+export type BlogPost = z.infer<typeof postSchema>;
+export type BlogContent = z.infer<typeof blogContentSchema>;
+
+export const blogTemplate: PresenceTemplate<BlogContent, BlogTheme> = {
+  kind: 'presence',
+  id: 'blog',
+  name: 'Otwarty Blog',
+  version: '1.0.0',
+  schema: blogContentSchema,
+  defaultContent: {
+    brand: { siteName: 'Mój blog', description: 'Notatki, eseje, myśli.' },
+    posts: [],
+  },
+  editor: {
+    fields: [
+      { key: 'brand.siteName', label: 'Tytuł bloga', type: 'text', required: true },
+      { key: 'brand.description', label: 'Opis bloga', type: 'textarea', required: true },
+      {
+        key: 'posts',
+        label: 'Posty',
+        type: 'array',
+        itemSchema: [
+          { key: 'title', label: 'Tytuł', type: 'text', required: true },
+          { key: 'slug', label: 'Slug URL', type: 'text', required: true },
+          { key: 'pubDate', label: 'Data publikacji', type: 'date', required: true },
+          { key: 'excerpt', label: 'Zajawka', type: 'textarea' },
+          { key: 'body', label: 'Treść (markdown)', type: 'textarea', required: true },
+        ],
+      },
+    ],
+  },
+  routes(content) {
+    return [
+      { path: '/' },
+      { path: '/blog/:slug', enumerate: () => content.posts.map((p) => ({ slug: p.slug })) },
+      { path: '/rss.xml' },
+    ];
+  },
+  render(req, ctx) {
+    if (req.path === '/rss.xml') return renderRssXml(req, ctx);
+    if (req.params.slug) return renderPost(req, ctx);
+    return renderIndex(req, ctx);
+  },
+  sitemap(content, baseUrl) {
+    return [
+      { loc: `${baseUrl}/`, priority: 1.0, changefreq: 'weekly' },
+      ...content.posts.map((p) => ({ loc: `${baseUrl}/blog/${p.slug}`, lastmod: p.pubDate, priority: 0.7 })),
+    ];
+  },
+  feed(content, baseUrl): RssFeed {
+    return {
+      title: content.brand.siteName,
+      link: baseUrl,
+      description: content.brand.description,
+      items: content.posts.map((p) => ({
+        title: p.title,
+        link: `${baseUrl}/blog/${p.slug}`,
+        guid: `${baseUrl}/blog/${p.slug}`,
+        pubDate: p.pubDate,
+        description: p.excerpt,
+      })),
+    };
+  },
+  meta: { locale: 'pl-PL', description: 'Personal blog', suggestedTheme: 'specialist-glossy', tags: ['blog', 'markdown'] },
+};
+
+function renderIndex(req: RenderRequest<BlogContent>, ctx: RenderContext<BlogTheme>): RenderResult {
+  const { content } = req;
+  const items = content.posts
+    .map((p) => `<article><h2><a href="/blog/${ctx.theme.esc(p.slug)}">${ctx.theme.esc(p.title)}</a></h2><time>${ctx.theme.esc(p.pubDate)}</time>${p.excerpt ? `<p>${ctx.theme.esc(p.excerpt)}</p>` : ''}</article>`)
+    .join('\n');
+  return {
+    head: { title: content.brand.siteName, description: content.brand.description, canonical: `${ctx.baseUrl}/` },
+    body: ctx.theme.layout({ title: content.brand.siteName, description: content.brand.description }, `<h1>${ctx.theme.esc(content.brand.siteName)}</h1>${items}`),
+  };
+}
+
+function renderPost(req: RenderRequest<BlogContent>, ctx: RenderContext<BlogTheme>): RenderResult {
+  const post = req.content.posts.find((p) => p.slug === req.params.slug);
+  if (!post) return { status: 404, head: { title: '404' }, body: ctx.theme.layout({ title: '404' }, '<h1>404</h1>') };
+  return {
+    head: { title: `${post.title} | ${req.content.brand.siteName}`, description: post.excerpt, canonical: `${ctx.baseUrl}/blog/${post.slug}` },
+    body: ctx.theme.layout(
+      { title: post.title, description: post.excerpt },
+      `<article><h1>${ctx.theme.esc(post.title)}</h1><time>${ctx.theme.esc(post.pubDate)}</time>${ctx.theme.markdown(post.body)}</article>`,
+    ),
+  };
+}
+
+function renderRssXml(req: RenderRequest<BlogContent>, ctx: RenderContext<BlogTheme>): RenderResult {
+  // Engine zazwyczaj wywoła template.feed() i sam zbuduje XML — to fallback
+  // dla prostej ścieżki SSR gdzie chcemy odpowiedzieć bez warstwy engine'u.
+  const feed = blogTemplate.feed!(req.content, ctx.baseUrl)!;
+  const items = feed.items
+    .map((i) => `<item><title>${ctx.theme.esc(i.title)}</title><link>${i.link}</link><guid>${i.guid}</guid><pubDate>${i.pubDate}</pubDate>${i.description ? `<description>${ctx.theme.esc(i.description)}</description>` : ''}</item>`)
+    .join('');
+  const xml = `<?xml version="1.0"?><rss version="2.0"><channel><title>${ctx.theme.esc(feed.title)}</title><link>${feed.link}</link><description>${ctx.theme.esc(feed.description)}</description>${items}</channel></rss>`;
+  return { headers: { 'content-type': 'application/rss+xml' }, head: { title: '' }, body: xml };
+}

package/src/template-trener.ts

@@ -0,0 +1,282 @@
+/**
+ * template-trener — referencyjna implementacja PresenceTemplate.
+ *
+ * Zawiera pełen flow który dziś jest w OTWARTY-TRENER/landing/src/index.tsx,
+ * tylko jako czyste funkcje renderujące zamiast handlerów Hono. Engine
+ * wywoła render() per request (SSR) albo per route (SSG); template nie
+ * wie który tryb jest aktywny i nie powinien tego sprawdzać.
+ */
+
+import { z } from 'zod';
+import type {
+  PresenceTemplate,
+  RenderRequest,
+  RenderContext,
+  RenderResult,
+  SitemapEntry,
+} from './types';
+
+/* ─────────────── Theme contract dla tego templatu ───────────────
+ * Każdy template deklaruje JAKIEGO theme'u potrzebuje. Engine pilnuje
+ * przez generics że theme przekazany do createWorker() ma te same metody.
+ * Trener używa zestawu z @press2ai/theme-specialist-glossy.
+ */
+export interface TrenerTheme {
+  layout(props: { title: string; description?: string; jsonLd?: object; headExtra?: string }, body: string): string;
+  catalogHero(p: { badge?: string; title: string; subtitle?: string; searchAction?: string; searchPlaceholder?: string; searchValue?: string }): string;
+  catalogGrid(p: { title: string; filters?: string; cards: string }): string;
+  statBar(items: { value: string; label: string; icon?: string }[], summary?: string): string;
+  categoryNav(items: { href: string; label: string }[], ariaLabel?: string): string;
+  pagination(p: { current: number; total: number; extraParams?: string }): string;
+  profileCard(p: TrenerProfile, href: string): string;
+  profileArticle(p: TrenerProfile): string;
+  esc(s: string): string;
+}
+
+/* ─────────────── Schema treści ─────────────── */
+
+const profileSchema = z.object({
+  slug: z.string(),
+  firstName: z.string(),
+  lastName: z.string(),
+  jobTitle: z.string().default('Trener personalny'),
+  city: z.string().optional(),
+  bio: z.string().optional(),
+  photo: z.string().url().optional(),
+  specialties: z.array(z.string()).default([]),
+  languages: z.array(z.string()).default([]),
+  business: z
+    .object({
+      name: z.string().optional(),
+      taxId: z.string().optional(),
+      classification: z.array(z.string()).default([]),
+    })
+    .default({}),
+  social: z.record(z.string(), z.string()).default({}),
+});
+
+export type TrenerProfile = z.infer<typeof profileSchema>;
+
+const trenerContentSchema = z.object({
+  brand: z.object({
+    siteName: z.string(),
+    description: z.string(),
+  }),
+  copy: z.object({
+    heroBadge: z.string().optional(),
+    heroTitle: z.string(),
+    heroSubtitle: z.string().optional(),
+    searchPlaceholder: z.string().default('Szukaj...'),
+  }),
+  profiles: z.array(profileSchema),
+  cities: z.array(z.object({ name: z.string(), count: z.number() })).default([]),
+});
+
+export type TrenerContent = z.infer<typeof trenerContentSchema>;
+
+const PAGE_SIZE = 12;
+
+/* ─────────────── Template ─────────────── */
+
+export const trenerTemplate: PresenceTemplate<TrenerContent, TrenerTheme> = {
+  kind: 'presence',
+  id: 'trener',
+  name: 'Otwarty Trener',
+  version: '1.0.0',
+
+  schema: trenerContentSchema,
+
+  defaultContent: {
+    brand: {
+      siteName: 'Otwarty Trener',
+      description: 'Otwarta baza trenerów personalnych w Polsce. Dane z CEIDG.',
+    },
+    copy: {
+      heroBadge: 'Dane z publicznego rejestru CEIDG',
+      heroTitle: 'Znajdź trenera w Twojej okolicy',
+      heroSubtitle: 'Otwarty katalog trenerów. Bezpłatnie i bez rejestracji.',
+      searchPlaceholder: 'Szukaj po nazwisku, mieście lub firmie...',
+    },
+    profiles: [],
+    cities: [],
+  },
+
+  editor: {
+    fields: [
+      { key: 'brand.siteName', label: 'Nazwa serwisu', type: 'text', required: true },
+      { key: 'brand.description', label: 'Opis serwisu', type: 'textarea', required: true },
+      { key: 'copy.heroBadge', label: 'Badge nad nagłówkiem', type: 'text' },
+      { key: 'copy.heroTitle', label: 'Nagłówek hero', type: 'text', required: true },
+      { key: 'copy.heroSubtitle', label: 'Podtytuł hero', type: 'textarea' },
+      { key: 'copy.searchPlaceholder', label: 'Placeholder wyszukiwarki', type: 'text' },
+    ],
+    sections: [
+      { id: 'brand', title: 'Marka', fieldKeys: ['brand.siteName', 'brand.description'] },
+      { id: 'hero', title: 'Sekcja hero', fieldKeys: ['copy.heroBadge', 'copy.heroTitle', 'copy.heroSubtitle', 'copy.searchPlaceholder'] },
+    ],
+  },
+
+  dataSources: [
+    {
+      // CEIDG fetcher — w produkcji bije do dane.biznes.gov.pl, mapuje do
+      // profiles[]. Tu STUB — kontrakt: dostaje NIP, zwraca Partial<TrenerContent>.
+      id: 'ceidg',
+      refresh: 'daily',
+      async fetch({ taxId }) {
+        if (!taxId) return {};
+        return { profiles: [] };
+      },
+    },
+  ],
+
+  routes(content) {
+    return [
+      { path: '/', cacheControl: 'public, s-maxage=300' },
+      {
+        path: '/:slug',
+        enumerate: () => content.profiles.map((p) => ({ slug: p.slug })),
+        cacheControl: 'public, s-maxage=300',
+      },
+    ];
+  },
+
+  render(req, ctx) {
+    if (req.params.slug) return renderProfile(req, ctx);
+    return renderIndex(req, ctx);
+  },
+
+  sitemap(content, baseUrl) {
+    const entries: SitemapEntry[] = [
+      { loc: `${baseUrl}/`, priority: 1.0, changefreq: 'daily' },
+    ];
+    for (const p of content.profiles) {
+      entries.push({ loc: `${baseUrl}/${p.slug}`, priority: 0.8, changefreq: 'weekly' });
+    }
+    return entries;
+  },
+
+  meta: {
+    locale: 'pl-PL',
+    description: 'Katalog trenerów personalnych',
+    suggestedTheme: 'specialist-glossy',
+    tags: ['katalog', 'wizytówka', 'rejestr-publiczny'],
+  },
+};
+
+/* ─────────────── Render handlers (private) ─────────────── */
+
+function renderIndex(req: RenderRequest<TrenerContent>, ctx: RenderContext<TrenerTheme>): RenderResult {
+  const { content } = req;
+  const t = ctx.theme;
+  const q = (req.query.q ?? '').trim();
+  const page = Math.max(1, parseInt(req.query.p ?? '1', 10) || 1);
+
+  let filtered = content.profiles;
+  if (q) {
+    const ql = q.toLowerCase();
+    filtered = filtered.filter(
+      (p) =>
+        `${p.firstName} ${p.lastName}`.toLowerCase().includes(ql) ||
+        (p.city ?? '').toLowerCase().includes(ql) ||
+        (p.business?.name ?? '').toLowerCase().includes(ql),
+    );
+  }
+
+  const total = filtered.length;
+  const totalPages = Math.max(1, Math.ceil(total / PAGE_SIZE));
+  const slice = filtered.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);
+
+  const hero = t.catalogHero({
+    badge: content.copy.heroBadge,
+    title: content.copy.heroTitle,
+    subtitle: content.copy.heroSubtitle,
+    searchAction: '/',
+    searchPlaceholder: content.copy.searchPlaceholder,
+    searchValue: q,
+  });
+
+  const stats = t.statBar([
+    { value: total.toLocaleString('pl'), label: 'trenerów', icon: 'people' },
+    { value: String(content.cities.length), label: 'miast', icon: 'city' },
+    { value: '100%', label: 'bezpłatnie', icon: 'free' },
+  ]);
+
+  const cityNav = t.categoryNav(
+    content.cities.slice(0, 8).map((c) => ({
+      href: `/?q=${encodeURIComponent(c.name)}`,
+      label: `${c.name} (${c.count})`,
+    })),
+    'Popularne miasta',
+  );
+
+  const cards = slice.map((p) => t.profileCard(p, `/${p.slug}`)).join('\n');
+  const grid = t.catalogGrid({
+    title: q ? `Wyniki dla „${t.esc(q)}" (${total})` : 'Trenerzy',
+    cards,
+  });
+
+  const pag = t.pagination({
+    current: page,
+    total: totalPages,
+    extraParams: q ? `&q=${encodeURIComponent(q)}` : '',
+  });
+
+  const body = `${hero}${stats}${cityNav}${grid}${pag}`;
+
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    name: content.brand.siteName,
+    url: ctx.baseUrl,
+    description: content.brand.description,
+  };
+
+  return {
+    head: {
+      title: q ? `${q} — ${content.brand.siteName}` : content.brand.siteName,
+      description: content.brand.description,
+      canonical: `${ctx.baseUrl}/`,
+      jsonLd,
+    },
+    body: t.layout({ title: content.brand.siteName, description: content.brand.description, jsonLd }, body),
+  };
+}
+
+function renderProfile(req: RenderRequest<TrenerContent>, ctx: RenderContext<TrenerTheme>): RenderResult {
+  const profile = req.content.profiles.find((p) => p.slug === req.params.slug);
+  if (!profile) {
+    return {
+      status: 404,
+      head: { title: 'Nie znaleziono' },
+      body: ctx.theme.layout({ title: 'Nie znaleziono' }, '<h1>404</h1><p>Brak takiego trenera.</p>'),
+    };
+  }
+
+  const t = ctx.theme;
+  const fullName = `${profile.firstName} ${profile.lastName}`;
+  const description = `${fullName} — ${profile.jobTitle}${profile.city ? ` w ${profile.city}` : ''}`;
+
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'Person',
+    name: fullName,
+    jobTitle: profile.jobTitle,
+    url: `${ctx.baseUrl}/${profile.slug}`,
+    ...(profile.city && {
+      address: { '@type': 'PostalAddress', addressLocality: profile.city, addressCountry: 'PL' },
+    }),
+  };
+
+  return {
+    head: {
+      title: `${fullName} — ${profile.city ?? ''} | ${req.content.brand.siteName}`,
+      description,
+      canonical: `${ctx.baseUrl}/${profile.slug}`,
+      jsonLd,
+    },
+    body: t.layout(
+      { title: `${fullName} | ${req.content.brand.siteName}`, description, jsonLd },
+      t.profileArticle(profile),
+    ),
+  };
+}

package/src/type-tests.ts

@@ -0,0 +1,28 @@
+/**
+ * Compile-time type tests. Plik nigdy nie biegnie w runtime — istnieje tylko
+ * po to żeby tsc krzyknął jeśli któryś referencyjny template przestanie
+ * spełniać OtwartyTemplate. Drugi cel: pokazać że ten sam template wchodzi
+ * jako input do wszystkich trzech trybów engine'u (SSR / SSG / Browser).
+ */
+
+import type { OtwartyTemplate, PresenceTemplate } from './types';
+import { trenerTemplate, type TrenerContent, type TrenerTheme } from './template-trener';
+import { blogTemplate, type BlogContent, type BlogTheme } from './template-blog';
+import type { createSSRWorker } from './runtime/ssr';
+import type { createSSGBuild, createBrowserRenderer } from './engine-signature';
+
+// 1. Każdy template jest poprawnym OtwartyTemplate
+const _trener: OtwartyTemplate<TrenerContent, TrenerTheme> = trenerTemplate;
+const _blog: OtwartyTemplate<BlogContent, BlogTheme> = blogTemplate;
+
+// 2. Discriminator działa — TS narrowi 'const x = trenerTemplate' do PresenceTemplate
+//    nawet jeśli annotujemy szerzej. Wystarczy że union assignment kompiluje.
+const _presenceCheck: PresenceTemplate<TrenerContent, TrenerTheme> = trenerTemplate;
+
+// 3. Ten sam template jako input do wszystkich trzech trybów engine'u
+type _SSR = ReturnType<typeof createSSRWorker<TrenerContent, TrenerTheme>>;
+type _SSG = ReturnType<typeof createSSGBuild<TrenerContent, TrenerTheme>>;
+type _BROWSER = ReturnType<typeof createBrowserRenderer<TrenerContent, TrenerTheme>>;
+type _SSR_BLOG = ReturnType<typeof createSSRWorker<BlogContent, BlogTheme>>;
+
+export type { _SSR, _SSG, _BROWSER, _SSR_BLOG };

package/src/types.ts

@@ -0,0 +1,237 @@
+/**
+ * @press2ai/engine — core types
+ *
+ * Cały design stoi na jednej zasadzie:
+ *   render = pure function (content + theme + request) → html + meta
+ * Dzięki temu ten sam template uruchamiamy w trzech trybach:
+ *   - SSR: w CF Workerze multi-tenant (Faza 0, content z D1)
+ *   - SSG: build statyczny (Faza 1, deploy do CF Pages / Codeberg Pages)
+ *   - Browser: live preview w lokalnym edytorze
+ * Engine jest tylko cienką warstwą routingu + ładowania content; cała
+ * inteligencja siedzi w templatach.
+ */
+
+import type { ZodType, ZodTypeDef } from 'zod';
+
+/**
+ * Schema generic — `ZodType<C, ZodTypeDef, any>` zamiast `ZodType<C>` żeby
+ * akceptować schematy z `.default()` (gdzie input-type ≠ output-type).
+ * Bez tego template nie mógłby używać `z.array(...).default([])`.
+ */
+type ContentSchema<C> = ZodType<C, ZodTypeDef, any>;
+
+/* ─────────────── Discriminator: Presence vs Commerce ─────────────── */
+
+/**
+ * PresenceTemplate — wizytówki, blogi, portfolio, landingi.
+ * Działa w Fazie 0 (trial multi-tenant) i Fazie 1 (sovereign).
+ *
+ * CommerceTemplate — sklepy. Wymaga Fazy 1 (własne konta usera u
+ * operatorów płatności + na infrze). NIGDY nie tworzymy commerce
+ * tenanta pod kontami platformy — gate prawny (PCI DSS, JPK, RODO).
+ */
+export type OtwartyTemplate<C = unknown, T = unknown> =
+  | PresenceTemplate<C, T>
+  | CommerceTemplate<C, T>;
+
+interface BaseTemplate<C, T> {
+  /** Unikalny identyfikator templatu, np. 'trener', 'lekarz', 'blog'. */
+  id: string;
+  /** Nazwa do wyświetlenia w wizardzie / panelu. */
+  name: string;
+  /** Semver paczki npm — używane w wizardzie do migracji. */
+  version: string;
+
+  /** Zod schema kształtu treści. Engine waliduje przy zapisie. */
+  schema: ContentSchema<C>;
+  /** Domyślna treść dla świeżego tenanta (seed). */
+  defaultContent: C;
+
+  /** Auto-generowany formularz edytora (Faza 0). */
+  editor: EditorSchema;
+
+  /** Deklaratywne źródła danych (CEIDG, RPWDL, ...). Engine wywołuje. */
+  dataSources?: DataSource<C>[];
+
+  /** Wyliczenie istniejących URL-i dla danej treści. */
+  routes(content: C): RouteDescriptor<C>[];
+
+  /** Czysta funkcja renderowania. Wywoływana per request (SSR) lub per route (SSG). */
+  render(req: RenderRequest<C>, ctx: RenderContext<T>): RenderResult;
+
+  /** SEO + maszynowa odkrywalność. */
+  sitemap(content: C, baseUrl: string): SitemapEntry[];
+  robots?(content: C): string;
+  feed?(content: C, baseUrl: string): RssFeed | null;
+
+  /** Metadane templatu (nie treści). */
+  meta: TemplateMeta;
+}
+
+export interface PresenceTemplate<C = unknown, T = unknown> extends BaseTemplate<C, T> {
+  kind: 'presence';
+}
+
+export interface CommerceTemplate<C = unknown, T = unknown> extends BaseTemplate<C, T> {
+  kind: 'commerce';
+  /** Type-level gate: commerce zawsze wymaga Fazy 1. */
+  requiresPhase1: true;
+  /** Sloty providerów wypełniane przez wizard migracji. */
+  providers: CommerceProviders;
+  /** Demo mode — w Fazie 0 wolno pokazać podgląd, ale checkout musi być fake. */
+  demoMode?: { fakeCheckout: true };
+}
+
+/* ─────────────── Routes & rendering ─────────────── */
+
+export interface RouteDescriptor<C> {
+  /** Wzorzec URL-a, np. '/' albo '/blog/:slug'. */
+  path: string;
+  /** Dla SSG: wylicz wszystkie konkretne wartości parametrów z treści. */
+  enumerate?(content: C): Array<Record<string, string>>;
+  /** Hint dla CDN cache. */
+  cacheControl?: string;
+}
+
+export interface RenderRequest<C> {
+  /** Konkretna ścieżka URL (już dopasowana do route'a). */
+  path: string;
+  /** Dopasowane parametry route'a, np. { slug: 'anna-kowalska' }. */
+  params: Record<string, string>;
+  /** Query string, np. { q: 'warszawa', p: '2' }. */
+  query: Record<string, string>;
+  /** Treść tenanta (już załadowana przez engine). */
+  content: C;
+}
+
+export interface RenderContext<T> {
+  /** Bezwzględny URL bazowy (host + scheme), np. 'https://anna.otwarty-trener.pl'. */
+  baseUrl: string;
+  /** Theme (theme-specialist-glossy itd.). Type T określa kontrakt per template. */
+  theme: T;
+  /** Lokalizacja, np. 'pl-PL'. */
+  locale: string;
+  /** Tryb wykonania — pozwala templatom uniknąć dynamiki w SSG. */
+  mode: 'ssr' | 'ssg' | 'browser';
+}
+
+export interface RenderResult {
+  status?: number;
+  headers?: Record<string, string>;
+  head: HeadMeta;
+  body: string;
+}
+
+export interface HeadMeta {
+  title: string;
+  description?: string;
+  canonical?: string;
+  og?: { image?: string; type?: string; url?: string };
+  jsonLd?: object | object[];
+  /** Surowy HTML do wstawienia w <head> (tylko gdy naprawdę trzeba). */
+  extra?: string;
+}
+
+/* ─────────────── Editor (Faza 0) ─────────────── */
+
+export interface EditorSchema {
+  fields: EditorField[];
+  sections?: EditorSection[];
+}
+
+export interface EditorField {
+  /** Ścieżka w content, np. 'profile.bio' (kropka = zagnieżdżenie). */
+  key: string;
+  label: string;
+  type: 'text' | 'textarea' | 'email' | 'url' | 'phone' | 'image' | 'select' | 'array' | 'date';
+  required?: boolean;
+  placeholder?: string;
+  help?: string;
+  /** Dla 'select'. */
+  options?: string[];
+  /** Dla 'array' — schemat pojedynczego elementu. */
+  itemSchema?: EditorField[];
+}
+
+export interface EditorSection {
+  id: string;
+  title: string;
+  fieldKeys: string[];
+}
+
+/* ─────────────── Data sources ─────────────── */
+
+export interface DataSource<C> {
+  id: string;
+  /** Engine wywołuje z kluczami identyfikacyjnymi (NIP, email, ...). */
+  fetch(input: DataSourceInput): Promise<Partial<C>>;
+  /** Częstotliwość auto-refresh w trybie sovereign (manual = nigdy). */
+  refresh?: 'manual' | 'daily' | 'weekly';
+}
+
+export interface DataSourceInput {
+  taxId?: string;
+  email?: string;
+  slug?: string;
+}
+
+/* ─────────────── SEO / discovery ─────────────── */
+
+export interface SitemapEntry {
+  loc: string;
+  lastmod?: string;
+  changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+  priority?: number;
+}
+
+export interface RssFeed {
+  title: string;
+  link: string;
+  description: string;
+  items: RssItem[];
+}
+
+export interface RssItem {
+  title: string;
+  link: string;
+  guid: string;
+  pubDate: string;
+  description?: string;
+  content?: string;
+}
+
+/* ─────────────── Commerce providers ─────────────── */
+
+export interface CommerceProviders {
+  payment: ProviderSlot<PaymentProviderId>;
+  shipping?: ProviderSlot<ShippingProviderId>;
+  invoice?: ProviderSlot<InvoiceProviderId>;
+}
+
+export type PaymentProviderId = 'stripe' | 'p24' | 'payu' | 'blik' | 'paypal';
+export type ShippingProviderId = 'inpost' | 'dpd' | 'pickup' | 'manual';
+export type InvoiceProviderId = 'gus' | 'fakturownia' | 'manual';
+
+export interface ProviderSlot<T extends string> {
+  required: boolean;
+  available: T[];
+  default?: T;
+}
+
+/* ─────────────── Engine outputs ─────────────── */
+
+/** Plik wyprodukowany przez SSG build. */
+export interface BuildFile {
+  path: string; // np. '/index.html', '/blog/foo/index.html', '/sitemap.xml'
+  content: string;
+  contentType: string;
+}
+
+export interface TemplateMeta {
+  locale: string;
+  description: string;
+  /** Sugerowany theme — engine użyje go, jeśli user nie wybierze innego. */
+  suggestedTheme?: string;
+  /** Tagi do wyświetlania w katalogu templatów ('wizytówka', 'blog', 'sklep'). */
+  tags?: string[];
+}