feat: add APIMart AI generation and guided Studio onboarding

app/lib/studio-ai.ts

@@ -0,0 +1,190 @@
+import type {
+  GenerationProvider,
+  GenerationRequest,
+} from "@wrnexus/design-studio";
+
+export const APIMART_MODEL = "gpt-6-luna";
+export function apimartProvider(
+  apiKey: string,
+  transport: typeof fetch = fetch,
+): GenerationProvider {
+  return {
+    name: "APIMart",
+    async generate(prompt, options = {}) {
+      const response = await transport(
+        "https://api.apimart.ai/v1/chat/completions",
+        {
+          method: "POST",
+          signal: options.signal,
+          redirect: "error",
+          headers: {
+            authorization: `Bearer ${apiKey}`,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({
+            model: APIMART_MODEL,
+            stream: false,
+            max_tokens: options.maxTokens ?? 4096,
+            messages: [
+              {
+                role: "system",
+                content:
+                  options.system ?? "Return valid design proposal JSON only.",
+              },
+              { role: "user", content: prompt },
+            ],
+          }),
+        },
+      );
+      // Never forward upstream bodies: they may echo credentials or submitted context.
+      if (!response.ok)
+        throw Error(`APIMart request failed (${response.status}).`);
+      const raw = await readBounded(response, 200_000);
+      const result = JSON.parse(raw);
+      const choice = result.choices?.[0];
+      if (choice?.finish_reason === "length")
+        throw Error("APIMart output was truncated.");
+      if (
+        typeof choice?.message?.content !== "string" ||
+        !choice.message.content.trim()
+      )
+        throw Error("APIMart returned no design proposal.");
+      return {
+        value: choice.message.content,
+        provider: "APIMart",
+        model: APIMART_MODEL,
+      };
+    },
+  };
+}
+
+async function readBounded(source: Request | Response, limit: number) {
+  const reader = source.body?.getReader();
+  const decoder = new TextDecoder();
+  let text = "",
+    bytes = 0;
+  if (!reader) return text;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > limit) {
+        await reader.cancel();
+        throw Error("Request or response is too large.");
+      }
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+    return text + decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+export function studioAI(apiKey?: string, transport: typeof fetch = fetch) {
+  let active = 0,
+    windowStart = Date.now(),
+    count = 0;
+  const json = (value: unknown, status = 200) =>
+    new Response(JSON.stringify(value), {
+      status,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    });
+  return async (request: Request): Promise<Response | undefined> => {
+    const url = new URL(request.url);
+    if (
+      !apiKey ||
+      ![
+        "/design-studio/api/generation",
+        "/design-studio/api/generate",
+      ].includes(url.pathname)
+    )
+      return;
+    const scheme = request.headers.get("x-forwarded-proto");
+    if (scheme === "https" || scheme === "http") url.protocol = scheme + ":";
+    if (
+      request.headers.get("origin") &&
+      request.headers.get("origin") !== url.origin
+    )
+      return json({ error: "Same-origin requests only." }, 403);
+    if (url.pathname.endsWith("/generation") && request.method === "GET")
+      return json({
+        provider: "APIMart",
+        model: APIMART_MODEL,
+        templateVersion: 1,
+        maxAttempts: 2,
+        maxOutputTokens: 4096,
+        timeoutMs: 20000,
+      });
+    if (!url.pathname.endsWith("/generate") || request.method !== "POST")
+      return json({ error: "Method not allowed." }, 405);
+    if (
+      !(request.headers.get("content-type") ?? "").startsWith(
+        "application/json",
+      )
+    )
+      return json({ error: "JSON required." }, 415);
+    if (Date.now() - windowStart >= 60000) {
+      windowStart = Date.now();
+      count = 0;
+    }
+    if (active >= 2 || count >= 10)
+      return json(
+        { error: "AI generation is busy. Try again in a minute." },
+        429,
+      );
+    active++;
+    try {
+      const input = JSON.parse(
+        await readBounded(request, 2_000_000),
+      ) as GenerationRequest;
+      count++;
+      // Preserve the installed engine's validation, locks, revision checks and repair budget.
+      const module = import.meta.resolve("@wrnexus/design-studio");
+      const { generateDesigns } = (await import(
+        module
+      )) as typeof import("@wrnexus/design-studio");
+      const result = await generateDesigns(input, {
+        provider: apimartProvider(apiKey, transport),
+        model: APIMART_MODEL,
+        signal: request.signal,
+      });
+      return json(result);
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Invalid generation request.";
+      if (message.includes("WRN-STUDIO-CONFLICT"))
+        return json(
+          {
+            error: "Your draft changed. Generate again from the current draft.",
+          },
+          409,
+        );
+      if (message.includes("too large"))
+        return json({ error: "Request is too large." }, 413);
+      if (
+        request.signal.aborted ||
+        (error instanceof Error && error.name === "AbortError")
+      )
+        return json(
+          {
+            error:
+              "AI generation timed out or was cancelled. Your draft is unchanged.",
+          },
+          408,
+        );
+      return json(
+        {
+          error:
+            "Could not generate a design. Check the brief and server AI configuration. Your draft is unchanged.",
+        },
+        400,
+      );
+    } finally {
+      active--;
+    }
+  };
+}

app/lib/studio-guide.ts

@@ -0,0 +1,11 @@
+export const studioHelpScript = `window.addEventListener("error",function(){var s=document.getElementById("validation-state"),d=document.getElementById("diagnostics");if(s&&s.textContent==="Checking"){s.textContent="Editor could not start";if(d)d.textContent="Reload the page. If this continues, rebuild and restart the site with the latest Studio configuration. Your saved draft has not been deleted.";}});document.addEventListener("DOMContentLoaded",function(){var b=document.querySelector('[data-tab="guided"]');if(b)b.click();});`;
+
+export function addStudioGuide(html: string, configured: boolean) {
+  const guide = `<details open class="help"><summary><strong>How to use Design Studio</strong></summary><ol><li><strong>Describe your website.</strong> Open Guided design, enter your product and audience, then choose colors, shapes and spacing with Next.</li><li><strong>Generate and compare.</strong> Click Generate three directions, review an alternative, then choose Use reviewed proposal.</li><li><strong>Refine it.</strong> Try “make buttons square and use blue as the primary color” under Edit with words. Lock decisions you want to keep.</li><li><strong>Use it in your app.</strong> Open Review &amp; apply and export Theme config or Compiled CSS. This website previews and exports designs; it does not change your deployed app automatically.</li></ol><p>${configured ? "APIMart AI is enabled with gpt-6-luna. Generation sends your brief and current design to APIMart only when you request it." : "AI is not configured. Local presets and supported rule-based edits still work. Set APIMART_API_KEY in the server .env and restart to enable gpt-6-luna."}</p></details>`;
+  return html
+    .replace(
+      '<script type="module"',
+      '<script src="./site-help.js"></script><script type="module"',
+    )
+    .replace('<div id="diagnostics"', guide + '<div id="diagnostics"');
+}

app/middleware/design-studio.ts

@@ -1,7 +1,10 @@
 import type { Middleware } from "@wrnexus/core";
 import type { createStudioHandler } from "@wrnexus/design-studio/server";
+import { studioAI } from "../lib/studio-ai.ts";
+import { addStudioGuide, studioHelpScript } from "../lib/studio-guide.ts";
 
 let studio: ReturnType<typeof createStudioHandler> | undefined;
+let ai: ReturnType<typeof studioAI> | undefined;
 
 const designStudio: Middleware = async (ctx, next) => {
   const url = new URL(ctx.req.url);
@@ -11,6 +14,19 @@ const designStudio: Middleware = async (ctx, next) => {
       headers: { location: "/design-studio/" },
     });
   if (!url.pathname.startsWith("/design-studio/")) return next();
+  ai ??= studioAI(process.env.APIMART_API_KEY?.trim());
+  const generated = await ai(ctx.req);
+  if (generated) return generated;
+  if (
+    url.pathname === "/design-studio/site-help.js" &&
+    ctx.req.method === "GET"
+  )
+    return new Response(studioHelpScript, {
+      headers: {
+        "content-type": "text/javascript",
+        "cache-control": "no-store",
+      },
+    });
   // Load the installed package at runtime so its assets keep their package-relative URLs.
   const studioModule = import.meta.resolve("@wrnexus/design-studio/server");
   studio ??= import(studioModule)
@@ -23,7 +39,23 @@ const designStudio: Middleware = async (ctx, next) => {
       studio = undefined;
       throw error;
     });
-  return (await studio)(ctx.req);
+  const response = await (await studio)(ctx.req);
+  if (
+    url.pathname === "/design-studio/" &&
+    response.ok &&
+    ctx.req.method === "GET"
+  ) {
+    const headers = new Headers(response.headers);
+    headers.delete("content-length");
+    return new Response(
+      addStudioGuide(
+        await response.text(),
+        !!process.env.APIMART_API_KEY?.trim(),
+      ),
+      { status: response.status, headers },
+    );
+  }
+  return response;
 };
 
 export default designStudio;

app/types/wrnexus.generated.d.ts

@@ -16,7 +16,7 @@ declare namespace WRNexusGenerated {
   type RouteName = "accessibility" | "advanced.forms" | "base" | "block.library" | "blocks" | "blocks.announcement.bar" | "blocks.ctasection" | "blocks.feature.card" | "blocks.feature.grid" | "blocks.feature.icon.card" | "blocks.footer" | "blocks.hero" | "blocks.hero.actions" | "blocks.marketing.section.header" | "blocks.metric.grid" | "blocks.page.header" | "blocks.section.header" | "blocks.split.hero" | "blocks.stats.bar" | "colors" | "components.accordion" | "components.advanced.select" | "components.alert" | "components.avatar" | "components.avatar.group" | "components.back.to.top" | "components.badge" | "components.blockquote" | "components.breadcrumb" | "components.button" | "components.button.group" | "components.card" | "components.carousel" | "components.chart" | "components.chat.bubble" | "components.checkbox" | "components.clipboard" | "components.collapse" | "components.color.picker" | "components.columns" | "components.combo.box" | "components.confetti" | "components.container" | "components.context.menu" | "components.custom.scrollbar" | "components.data.map" | "components.data.table" | "components.date.picker" | "components.device.frame" | "components.divider" | "components.drag.and.drop" | "components.drawer" | "components.drawflow.canvas" | "components.dropdown" | "components.file.input" | "components.file.upload.progress" | "components.flow.canvas" | "components.grid" | "components.image" | "components.input" | "components.input.group" | "components.input.number" | "components.kbd" | "components.layout.splitter" | "components.legend.indicator" | "components.link" | "components.list" | "components.list.group" | "components.map" | "components.marquee" | "components.mega.menu" | "components.metric.card" | "components.modal" | "components.nav" | "components.navbar" | "components.pagination" | "components.pin.input" | "components.popover" | "components.preference.switcher" | "components.progress" | "components.radio" | "components.range.slider" | "components.rating" | "components.scrollspy" | "components.search.box" | "components.section" | "components.select" | "components.sidebar" | "components.skeleton" | "components.spinner" | "components.stepper" | "components.strong.password" | "components.styled.icon" | "components.switch" | "components.tabs" | "components.text.link" | "components.textarea" | "components.time.picker" | "components.timeline" | "components.toaster" | "components.toggle.count" | "components.toggle.password" | "components.tooltip" | "components.tree.view" | "components.typography" | "components.wysiwyg.editor" | "core" | "dark.mode" | "data" | "docs" | "fonts" | "forms" | "framework.guides" | "index" | "installation" | "integrations" | "layout" | "marketing" | "navigation" | "overlays" | "preview" | "preview.custom.modal" | "preview.profile" | "preview.project.board" | "preview.scheduling" | "preview.sign.in" | "preview.workspace" | "resources" | "sizing" | "tables" | "templates" | "templates.commerce" | "templates.dashboards" | "templates.marketing" | "templates.productivity" | "themes" | "v06.functions" | "v06.imports" | "v06.migration" | "v06.outputs" | "v06.runtime" | "v06.state" | "v06.stores" | "v06.types";
   type ApiRoute = "/api/teams";
   type RealtimeRoute = never;
-  type EnvironmentKey = never;
+  type EnvironmentKey = "APIMART_API_KEY";
   type TranslationKey = never;
   type QueueName = never;
   type CacheKey = never;