Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
feat(web): add seven agent setup tutorials (#1097)
Gustavo Ye5876bc71ec4d
diff --git a/src/web/blog/README.md b/src/web/blog/README.mdindex 8e8c51c4a..a25f06bf2 100644--- a/src/web/blog/README.md+++ b/src/web/blog/README.md@@ -32,6 +32,12 @@ Include useful explanations, evidence, and relevant links.- Register every published article once in `src/lib/blog/topics.ts`, with its real topic and reader job. A draft uses `draft: true` and must stay out of public discovery/navigation.- Use valid article paths and existing heading fragments for internal links. Prefer links that help the reader over a required link count. When publishing, check whether a relevant older article should link to this one.+## Independent step guides++Structured onboarding pages use `/tutorials/<slug>`, registered in `src/web/src/lib/step-guides.ts` and rendered by `src/app/tutorials/[slug]/page.tsx` in this Blog app. They appear in the `/tutorials` directory; existing MDX guides keep `/blog/<slug>` URLs. Register the canonical title and description once. The main sitemap consumes this registry, so a release introducing a route must include both Blog and main sitemap changes.++Step guides render their text and mock UI on the server. Animation code loads only when its scene enters the viewport; provide explicit playback, reduced-motion static content, pause/cleanup and failure recovery. `scripts/validate-step-guides.ts` checks the rendered headings, body, canonical, metadata, anchors, CTA and footer during the Blog build. They do not enter the MDX discovery manifest or RSS.+## Main Blog or Guides?**Same-topic content variants must use `tags: ["guides"]`.** For example, applying the same collaboration problem to another coding-agent combination belongs in the supplementary `/guides` directory, not another similar main-Blog post. If the question and answer are unchanged, revise/link the existing article instead of creating a duplicate. Main-Blog additions need a distinct reader question explained during editorial review; the build cannot infer semantic similarity.@@ -67,7 +73,7 @@ pnpm --filter @alook/web build:blogThis includes source validation, image preparation, Next compilation, and rendered article validation before Worker packaging. The final packaging step stages the prerendered cache into Workers Static Assets, so the read-only cache works with raw Wrangler deployment as well. `build:blog:next` is the internal Next/standalone preparation step used by that command. `validate:blog` alone checks source files; it is not the full publishing gate.-Build errors include missing/invalid required metadata, invalid optional SEO title, duplicate H1 in Markdown, invalid/missing/oversized source images; then, in rendered articles: missing body/title/description, a missing or extra H1, incorrect canonical, noindex, duplicate heading IDs, conflicting/unparseable BlogPosting JSON-LD, missing local article/fragment/image resources, and inconsistent image or OG dimensions. Generated responsive resources must exist. Drafts must not become prerendered public articles. The full published article set must match topics and the discovery manifest (which supplies the main site sitemap). The main index and RSS contain only articles without the `guides` tag; `/guides` contains only articles with that tag. Their two index sets must partition the published articles. Footer navigation may link to the `/guides` directory, but must not link to individual guide articles. Keep exploring / Next Blog recommendations must not include the Guides directory or guide articles.+Build errors include missing/invalid required metadata, invalid optional SEO title, duplicate H1 in Markdown, invalid/missing/oversized source images; then, in rendered articles: missing body/title/description, a missing or extra H1, incorrect canonical, noindex, duplicate heading IDs, conflicting/unparseable BlogPosting JSON-LD, missing local article/fragment/image resources, and inconsistent image or OG dimensions. Generated responsive resources must exist. Drafts must not become prerendered public articles. The full published article set must match topics and the discovery manifest (which supplies the main site sitemap). The main index and RSS contain only articles without the `guides` tag; `/guides` lists tagged MDX articles. Separate step guides live in `/tutorials`. Their two index sets must partition the published articles. Footer navigation may link to the `/guides` directory, but must not link to individual guide articles. Keep exploring / Next Blog recommendations must not include the Guides directory or guide articles.The existing topic tests compare published MDX and the topic registry in both directions. Run related tests when changing templates or publication behavior; negative fixtures must demonstrate that invalid output actually fails. Keep `image-assets.json` regenerated with any source-image change so a clean checkout can typecheck before its first build.diff --git a/src/web/blog/custom-worker.test.ts b/src/web/blog/custom-worker.test.tsindex 6ac6f1b4e..06403236d 100644--- a/src/web/blog/custom-worker.test.ts+++ b/src/web/blog/custom-worker.test.ts@@ -34,7 +34,7 @@ describe("Blog Worker entrypoint", () => {worker = new BlogWorker({} as ExecutionContext, { ASSETS: {} as Fetcher });});- it.each(["/blog", "/guides", "/guides/"])("finalizes public document headers for %s", async (path) => {+ it.each(["/blog", "/guides", "/guides/", "/tutorials", "/tutorials/", "/tutorials/codex-and-claude-code", "/tutorials/codex-and-claude-code/"])("finalizes public document headers for %s", async (path) => {const response = await worker.fetch(new Request(`https://alook.ai${path}`));expect(await response.text()).toBe("node-open-next");expect(response.headers.get("Cache-Control")).toBe("public, max-age=0, must-revalidate");diff --git a/src/web/blog/custom-worker.ts b/src/web/blog/custom-worker.tsindex 2dbe96581..43aaf1e1c 100644--- a/src/web/blog/custom-worker.ts+++ b/src/web/blog/custom-worker.ts@@ -20,7 +20,7 @@ export default class BlogWorker extends WorkerEntrypoint<BlogCloudflareEnv> {const pathname = new URL(request.url).pathname;if (pathname === MANIFEST_PATH) return new Response("Not Found", { status: 404 });const response = await fetchOpenNext(request, this.env, this.ctx);- const publicDocument = pathname === "/blog" || /^\/guides\/?$/.test(pathname) || /^\/blog\/[^/.]+\/?$/.test(pathname);+ const publicDocument = pathname === "/blog" || /^\/tutorials(?:\/[^/.]+)?\/?$/.test(pathname) || /^\/guides\/?$/.test(pathname) || /^\/blog\/[^/.]+\/?$/.test(pathname);return finalizePublicWorkerResponse(response, publicDocument, request);}diff --git a/src/web/blog/scripts/validate-rendered.test.ts b/src/web/blog/scripts/validate-rendered.test.tsindex 33a00fd17..c593767bc 100644--- a/src/web/blog/scripts/validate-rendered.test.ts+++ b/src/web/blog/scripts/validate-rendered.test.ts@@ -50,6 +50,9 @@ describe("rendered article contract", () => {});});+const tutorialFixtures = vi.hoisted(() => ({ guides: [] as { slug: string; title: string }[] }));+vi.mock("../../src/lib/step-guides", () => ({ stepGuides: tutorialFixtures.guides }));+vi.mock("../src/lib/blog/topics", () => ({ blogTopics: [{ entries: [{ slug: "example" }] }] }));import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";@@ -72,6 +75,7 @@ describe("Blog build gate", () => {put(".next/server/app/blog/feed.xml.body", "<rss><channel><item><link>https://alook.ai/blog/example</link></item></channel></rss>");put(".next/server/app/blog.html", '<a href="/blog/example">Example</a>');put(".next/server/app/guides.html", "<h1>Guides</h1>");+ put(".next/server/app/tutorials.html", "<h1>Tutorials</h1>");expect(() => validateBlogBuild(root)).not.toThrow();put(".next/server/app/blog/example.html", html.replace("<h1>Example</h1>", ""));expect(() => validateBlogBuild(root)).toThrow("one H1");@@ -99,8 +103,16 @@ describe("Blog build gate", () => {put(".next/server/app/blog/example.html", html);put("src/content/draft.mdx", source({ ...metadata, slug: "draft", draft: true }));expect(() => validateBlogBuild(root)).not.toThrow();+ tutorialFixtures.guides.push({ slug: "two-agents", title: "Two agents" });+ put(".next/server/app/tutorials.html", '<a href="/tutorials/two-agents">Two agents</a>');+ const tutorial = `<title>Two agents</title><meta name="description" content="Connect two agents"><meta property="og:image" content="https://alook.ai/og.png"><link rel="canonical" href="https://alook.ai/tutorials/two-agents"><article data-step-guide><h1>Two agents</h1>${["one", "two", "three", "four"].map(id => `<section id="${id}"><h2>${id}</h2><p>${"Complete this step. ".repeat(10)}</p></section>`).join("")}<a href="/c">Open Alook</a></article><footer>Home</footer>`;+ put(".next/server/app/tutorials/two-agents.html", tutorial);+ expect(() => validateBlogBuild(root)).not.toThrow();+ put(".next/server/app/tutorials/two-agents.html", tutorial.replace("<footer>Home</footer>", ""));+ expect(() => validateBlogBuild(root)).toThrow("missing footer");+ put(".next/server/app/tutorials/two-agents.html", tutorial);put(".next/server/app/blog/draft.html", html);expect(() => validateBlogBuild(root)).toThrow("Draft was prerendered");- } finally { rmSync(root, { recursive: true, force: true }); }+ } finally { tutorialFixtures.guides.length = 0; rmSync(root, { recursive: true, force: true }); }});});diff --git a/src/web/blog/scripts/validate-rendered.ts b/src/web/blog/scripts/validate-rendered.tsindex a04507af5..a4bb30c90 100644--- a/src/web/blog/scripts/validate-rendered.ts+++ b/src/web/blog/scripts/validate-rendered.ts@@ -8,6 +8,9 @@ import { blogTopics } from "../src/lib/blog/topics";import { parseBlogDiscoveryManifest } from "../../src/lib/blog-discovery-manifest";import { isDraftBlogPost, readBlogMetadata, type BlogMetadata } from "../src/lib/blog/validate-assets";+import { stepGuides } from "../../src/lib/step-guides";+import { validateStepGuide } from "./validate-step-guides";+const origin = "https://alook.ai";export type RenderedPost = { metadata: BlogMetadata; html: string };@@ -113,6 +116,14 @@ export function validateBlogBuild(blogRoot: string): void {const guidesIndex = readFileSync(resolve(serverRoot, "guides.html"), "utf8");samePosts("Blog index", articleLinks(mainIndex), mainSlugs);samePosts("Guides index", articleLinks(guidesIndex), guideSlugs);+ const guideDocument = new JSDOM(readFileSync(resolve(serverRoot, "tutorials.html"), "utf8")).window.document;+ const stepLinks = [...new Set([...guideDocument.querySelectorAll('a[href^="/tutorials/"]')].map((link) => link.getAttribute("href")!.slice(11)))];+ samePosts("Step guides index", stepLinks, stepGuides.map((guide) => guide.slug));+ for (const guide of stepGuides) {+ const html = readFileSync(resolve(serverRoot, `tutorials/${guide.slug}.html`), "utf8");+ const failures = validateStepGuide(html, guide);+ if (failures.length) throw new Error(failures.join("\n"));+ }for (const html of [mainIndex, ...posts.map((post) => post.html)]) {const doc = new JSDOM(html).window.document;for (const link of doc.querySelectorAll<HTMLAnchorElement>('footer a[href], [data-blog-recommendations] a[href]')) {diff --git a/src/web/blog/scripts/validate-step-guides.test.ts b/src/web/blog/scripts/validate-step-guides.test.tsnew file mode 100644index 000000000..4fc993251--- /dev/null+++ b/src/web/blog/scripts/validate-step-guides.test.ts@@ -0,0 +1,26 @@+import { describe, expect, it } from "vitest";+import { validateStepGuide } from "./validate-step-guides";++const guide = { slug: "two-agents", title: "Two agents" };+const html = `<title>Two agents</title><meta name="description" content="Connect two agents"><meta property="og:image" content="https://alook.ai/og.png"><link rel="canonical" href="https://alook.ai/tutorials/two-agents"><main><article data-step-guide="two-agents"><h1>Two agents</h1>${["one", "two", "three", "four"].map((id) => `<section id="${id}"><h2>${id}</h2><p>${"Complete this step using your own account. ".repeat(5)}</p></section>`).join("")}<a href="#one">Start</a><a href="/c">Open Alook</a></article></main><footer>Home</footer>`;++describe("step guide rendered contract", () => {+ it("accepts complete server-rendered content without scripts", () => {+ expect(validateStepGuide(html, guide)).toEqual([]);+ });+ it("ignores inert UI replicas while keeping article anchor checks", () => {+ const replica = '<div inert><input id="bot-name"><input id="bot-name"><a href="#">Demo</a></div>';+ expect(validateStepGuide(html + replica, guide)).toEqual([]);+ expect(validateStepGuide(html + replica + '<a href="#missing">Broken</a>', guide).join()).toContain("anchor target");+ expect(validateStepGuide(html + '<div id="one"></div>', guide).join()).toContain("duplicate anchor");+ });+ it.each([+ ['<h1>Two agents</h1>', '', 'matching H1'],+ ['https://alook.ai/tutorials/two-agents', 'https://alook.ai/blog/two-agents', 'canonical'],+ ['href="#one"', 'href="#missing"', 'anchor target'],+ ['<footer>Home</footer>', '', 'footer'],+ ['<h2>four</h2>', '', 'step headings'],+ ])("rejects incomplete output %s", (from, to, expected) => {+ expect(validateStepGuide(html.replace(from, to), guide).join()).toContain(expected);+ });+});diff --git a/src/web/blog/scripts/validate-step-guides.ts b/src/web/blog/scripts/validate-step-guides.tsnew file mode 100644index 000000000..ba3bf4015--- /dev/null+++ b/src/web/blog/scripts/validate-step-guides.ts@@ -0,0 +1,28 @@+import { createRequire } from "node:module";+const { JSDOM } = createRequire(import.meta.url)("jsdom") as { JSDOM: new (html: string) => { window: { document: Document } } };++export function validateStepGuide(html: string, guide: { slug: string; title: string }): string[] {+ const doc = new JSDOM(html).window.document;+ const errors: string[] = [];+ const check = (valid: unknown, message: string) => { if (!valid) errors.push(`/tutorials/${guide.slug}: ${message}`); };+ check(doc.querySelectorAll("h1").length === 1 && doc.querySelector("h1")?.textContent === guide.title, "expected one matching H1");+ check(doc.querySelector("title")?.textContent?.includes(guide.title), "missing title");+ check(doc.querySelector('meta[name="description"]')?.getAttribute("content"), "missing description");+ const canonicals = doc.querySelectorAll('link[rel="canonical"]');+ check(canonicals.length === 1 && canonicals[0].getAttribute("href") === `https://alook.ai/tutorials/${guide.slug}`, "invalid canonical");+ check(doc.querySelector('meta[property="og:image"]')?.getAttribute("content"), "missing social image");+ check(!doc.querySelector('meta[name="robots"]')?.getAttribute("content")?.includes("noindex"), "noindex");+ const article = doc.querySelector("[data-step-guide]");+ check(article && (article.textContent?.length ?? 0) > 400, "missing server-rendered guide body");+ check((article?.querySelectorAll("section[id] h2").length ?? 0) >= 4, "missing step headings");+ check(doc.querySelector('a[href="/c"]'), "missing CTA");+ check(doc.querySelector("footer"), "missing footer");+ // Inert UI replicas are illustrations, not document navigation or form controls.+ const ids = [...doc.querySelectorAll("[id]")].filter((node) => !node.closest("[inert]")).map((node) => node.id);+ check(ids.length === new Set(ids).size, "duplicate anchor");+ for (const link of doc.querySelectorAll('a[href^="#"]')) {+ if (link.closest("[inert]")) continue;+ check(doc.getElementById(link.getAttribute("href")!.slice(1)), "missing anchor target");+ }+ return errors;+}diff --git a/src/web/blog/src/app/blog/blog-footer.dom.test.tsx b/src/web/blog/src/app/blog/blog-footer.dom.test.tsxindex bdb1a3a3f..84af0928d 100644--- a/src/web/blog/src/app/blog/blog-footer.dom.test.tsx+++ b/src/web/blog/src/app/blog/blog-footer.dom.test.tsx@@ -13,7 +13,7 @@ describe("Blog footer", () => {expect(doc.querySelectorAll("footer")).toHaveLength(1);expect(doc.querySelector("main footer")).toBeNull();expect(doc.querySelector("main")?.nextElementSibling?.tagName).toBe("FOOTER");- expect([...doc.querySelectorAll("footer nav a")].map((a) => a.getAttribute("href"))).toEqual(["/templates", "/blog", "/guides", "/llms.txt", "/privacy"]);+ expect([...doc.querySelectorAll("footer nav a")].map((a) => a.getAttribute("href"))).toEqual(["/templates", "/blog", "/guides", "/tutorials", "/llms.txt", "/privacy"]);expect(doc.querySelector("a[aria-label=Discord]")?.getAttribute("href")).toBe("https://discord.com/invite/24PHyEHU3M");expect(doc.querySelectorAll(".blog-footer-socials a")).toHaveLength(3);expect(doc.querySelector(".blog-footer-slogan")?.textContent).toContain("Multi-Agent Collaboration for Team and Friends");diff --git a/src/web/blog/src/app/blog/blog-footer.tsx b/src/web/blog/src/app/blog/blog-footer.tsxindex 52d269f24..c17003218 100644--- a/src/web/blog/src/app/blog/blog-footer.tsx+++ b/src/web/blog/src/app/blog/blog-footer.tsx@@ -25,6 +25,7 @@ export function BlogFooter() {<ZoneLink href="/templates" zone="blog">Templates</ZoneLink><ZoneLink href="/blog" zone="blog">Blog</ZoneLink><ZoneLink href="/guides" zone="blog">Guides</ZoneLink>+ <ZoneLink href="/tutorials" zone="blog">Tutorials</ZoneLink><ZoneLink href="/llms.txt" zone="blog">llms.txt</ZoneLink><ZoneLink href="/privacy" zone="blog">Privacy</ZoneLink></nav>diff --git a/src/web/blog/src/app/error.tsx b/src/web/blog/src/app/error.tsxindex 8f746544e..d3c68c63a 100644--- a/src/web/blog/src/app/error.tsx+++ b/src/web/blog/src/app/error.tsx@@ -1,7 +1,7 @@"use client";-import { ErrorContent } from "@/components/error-content";+import { DeferredBlogError } from "@blog/components/deferred-blog-failure";export default function BlogError({ reset }: { error: Error & { digest?: string }; reset: () => void }) {- return <ErrorContent reset={reset} hardHomeNavigation />;+ return <DeferredBlogError reset={reset} />;}diff --git a/src/web/blog/src/app/failure-pages.dom.test.tsx b/src/web/blog/src/app/failure-pages.dom.test.tsxnew file mode 100644index 000000000..5f7cb1cd7--- /dev/null+++ b/src/web/blog/src/app/failure-pages.dom.test.tsx@@ -0,0 +1,32 @@+import type { ComponentProps, ReactNode } from "react";+import { describe, expect, it, vi } from "vitest";+import { render, screen, setupUser } from "@/test/react-dom-harness";+import BlogError from "./error";+import BlogNotFound, { metadata } from "./not-found";++vi.mock("@/components/typewriter-visual", () => ({+ TypewriterVisual: ({ paper }: { paper: ReactNode }) => <div>{paper}</div>,+}));+vi.mock("next/link", () => ({+ default: ({ children, ...props }: ComponentProps<"a">) => <a data-next-link="true" {...props}>{children}</a>,+}));++describe("Blog recovery routes", () => {+ it("passes the retry callback through the lazy error screen and leaves the Blog zone for home", async () => {+ const reset = vi.fn();+ const user = setupUser();+ render(<BlogError error={new Error("Render failed")} reset={reset} />);+ await user.click(await screen.findByRole("button", { name: "Try again" }));+ expect(reset).toHaveBeenCalledOnce();+ expect(screen.getByRole("link", { name: "Go home" })).toHaveAttribute("href", "/");+ expect(screen.getByRole("link", { name: "Go home" })).not.toHaveAttribute("data-next-link");+ });++ it("keeps missing pages out of search and gives a document link home", async () => {+ render(<BlogNotFound />);+ expect(await screen.findByText(/The page you're looking for/)).toBeVisible();+ expect(screen.getByRole("link", { name: "Go home" })).toHaveAttribute("href", "/");+ expect(screen.getByRole("link", { name: "Go home" })).not.toHaveAttribute("data-next-link");+ expect(metadata.robots).toEqual({ index: false, follow: true });+ });+});diff --git a/src/web/blog/src/app/guides/layout.dom.test.tsx b/src/web/blog/src/app/guides/layout.dom.test.tsxindex 2ef105e8c..ad23e0952 100644--- a/src/web/blog/src/app/guides/layout.dom.test.tsx+++ b/src/web/blog/src/app/guides/layout.dom.test.tsx@@ -29,7 +29,7 @@ describe("Guides layout", () => {const footer = within(screen.getByRole("contentinfo"));const navigation = within(footer.getByRole("navigation", { name: "Footer navigation" }));expect(navigation.getAllByRole("link").map((link) => link.getAttribute("href")))- .toEqual(["/templates", "/blog", "/guides", "/llms.txt", "/privacy"]);+ .toEqual(["/templates", "/blog", "/guides", "/tutorials", "/llms.txt", "/privacy"]);expect(navigation.getByRole("link", { name: "Blog", exact: true })).toHaveAttribute("data-next-link", "true");for (const name of ["Templates", "llms.txt", "Privacy"]) {expect(navigation.getByRole("link", { name, exact: true })).not.toHaveAttribute("data-next-link");diff --git a/src/web/blog/src/app/not-found.tsx b/src/web/blog/src/app/not-found.tsxindex c83fa47b7..2c6454d6e 100644--- a/src/web/blog/src/app/not-found.tsx+++ b/src/web/blog/src/app/not-found.tsx@@ -1,5 +1,5 @@import type { Metadata } from "next";-import { NotFoundContent } from "@/components/not-found-content";+import { DeferredBlogNotFound } from "@blog/components/deferred-blog-failure";export const metadata: Metadata = {title: "Page Not Found",@@ -8,5 +8,5 @@ export const metadata: Metadata = {};export default function BlogNotFound() {- return <NotFoundContent hardHomeNavigation />;+ return <DeferredBlogNotFound />;}diff --git a/src/web/blog/src/app/tutorials/[slug]/page.dom.test.tsx b/src/web/blog/src/app/tutorials/[slug]/page.dom.test.tsxnew file mode 100644index 000000000..b415ddae3--- /dev/null+++ b/src/web/blog/src/app/tutorials/[slug]/page.dom.test.tsx@@ -0,0 +1,36 @@+import { describe, expect, it, vi } from "vitest";+import { render, screen } from "@/test/react-dom-harness";+import { stepGuides, tutorialAgents } from "@/lib/step-guides";+import StepGuidePage, { generateMetadata, generateStaticParams } from "./page";++vi.mock("@blog/components/guides/mock-scenes", () => ({+ ConnectDemo: ({ agents }: { agents: string[] }) => <div data-testid="connect-pair">{agents.join("+")}</div>,+ BotsDemo: ({ runtime, agents }: { runtime: string; agents: string[] }) => <div data-testid="bot-pair" data-runtime={runtime}>{agents.join("+")}</div>,+}));+vi.mock("@blog/components/guides/server-demo", () => ({ ServerDemo: ({ agents }: { agents: string[] }) => <div data-testid="server-pair">{agents.join("+")}</div> }));+vi.mock("@blog/components/guides/message-demo", () => ({ MessageDemo: () => <div /> }));++describe("paired tutorial pages", () => {+ it("prerenders all seven routes", () => {+ expect(generateStaticParams()).toEqual(stepGuides.map(({ slug }) => ({ slug })));+ });+ it.each(stepGuides)("renders $slug with its own content and animation pair", async (guide) => {+ const params = Promise.resolve({ slug: guide.slug });+ const { container } = render(await StepGuidePage({ params }));+ expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent(guide.title);+ expect(screen.getByText(guide.description)).toBeVisible();+ expect(screen.getAllByRole("heading", { level: 2 })).toHaveLength(6);+ expect(screen.getByTestId("connect-pair")).toHaveTextContent(guide.agents.join("+"));+ expect(screen.getByTestId("server-pair")).toHaveTextContent(guide.agents.join("+"));+ expect(screen.getAllByTestId("bot-pair").map(node => node.dataset.runtime)).toEqual(guide.agents);+ for (const runtime of guide.agents) {+ const agent = tutorialAgents[runtime];+ expect(screen.getByRole("link", { name: agent.setupName, exact: true })).toHaveAttribute("href", agent.setupUrl);+ expect(container.querySelector(`#create-${runtime}`)).toHaveTextContent(`Create your ${agent.name} bot`);+ }+ for (const anchor of container.querySelectorAll('a[href^="#"]')) {+ expect(container.querySelector(anchor.getAttribute("href")!)).not.toBeNull();+ }+ expect(await generateMetadata({ params })).toMatchObject({ alternates: { canonical: `https://alook.ai/tutorials/${guide.slug}` } });+ });+});diff --git a/src/web/blog/src/app/tutorials/[slug]/page.tsx b/src/web/blog/src/app/tutorials/[slug]/page.tsxnew file mode 100644index 000000000..cd94f8ca2--- /dev/null+++ b/src/web/blog/src/app/tutorials/[slug]/page.tsx@@ -0,0 +1,117 @@+import { requiresExplicitModel } from "@alook/shared";+import Image from "next/image";+import { ProviderLogo } from "@/components/provider-logo";+import { notFound } from "next/navigation";+import { ArrowRight, ChevronDown, ChevronRight } from "lucide-react";+import { ZoneLink } from "@/components/public-layout";+import { buildPublicPageMetadata } from "@/lib/seo/public-page-metadata";+import { getStepGuide, stepGuides, tutorialAgents, type TutorialPair } from "@/lib/step-guides";+import { MessageDemo } from "@blog/components/guides/message-demo";+import { ServerDemo } from "@blog/components/guides/server-demo";+import { ConnectDemo, BotsDemo } from "@blog/components/guides/mock-scenes";+import { Prerequisites } from "@blog/components/guides/prerequisites";+import styles from "@blog/components/guides/guide.module.css";++export const dynamicParams = false;+export function generateStaticParams() {+ return stepGuides.map(({ slug }) => ({ slug }));+}+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {+ const guide = getStepGuide((await params).slug);+ if (!guide) notFound();+ return buildPublicPageMetadata({ title: guide.title, description: guide.description, path: `/tutorials/${guide.slug}` });+}+function guideSteps(agents: TutorialPair) {+ return [+ ["sign-in", "Sign in to Alook"],+ ["connect", "Connect your computer"],+ [`create-${agents[0]}`, `Create your ${tutorialAgents[agents[0]].name} bot`],+ [`create-${agents[1]}`, `Create your ${tutorialAgents[agents[1]].name} bot`],+ ["create-server", "Bring them into a server"],+ ["send-message", "Send your first message"],+ ] as const;+}++type Steps = ReturnType<typeof guideSteps>;+function Contents({ steps }: { steps: Steps }) {+ return <ol>{steps.map(([id, title]) => <li key={id}><a href={`#${id}`}>{title}</a></li>)}</ol>;+}+function Heading({ index, steps }: { index: number; steps: Steps }) {+ return <div className={styles.stepHeading}><span aria-hidden="true">{index + 1}</span><h2><a href={`#${steps[index][0]}`} className={styles.stepLink}>{steps[index][1]}<span aria-hidden="true">#</span></a></h2></div>;+}++function CompletionCriteria({ children }: { children: React.ReactNode }) {+ return <aside className={styles.completionCriteria} aria-label="Step completion criteria"><span aria-hidden="true">👌</span><p><strong>Before you continue,</strong> {children}</p></aside>;+}++export default async function StepGuidePage({ params }: { params: Promise<{ slug: string }> }) {+ const guide = getStepGuide((await params).slug);+ if (!guide) notFound();+ const [first, second] = guide.agents;+ const firstAgent = tutorialAgents[first];+ const secondAgent = tutorialAgents[second];+ const steps = guideSteps(guide.agents);+ return <div className={styles.page}>+ <nav className={styles.breadcrumb} aria-label="Breadcrumb">+ <ZoneLink href="/" zone="blog">Home</ZoneLink><ChevronRight size={12} aria-hidden="true" />+ <ZoneLink href="/tutorials" zone="blog">Tutorials</ZoneLink><ChevronRight size={12} aria-hidden="true" />+ <span aria-current="page">{firstAgent.name} + {secondAgent.name}</span>+ </nav>+ <div className={styles.layout}>+ <article className={styles.article} data-step-guide={guide.slug}>+ <header className={styles.header}>+ <h1>Use <span className={styles.titleProduct}><span aria-hidden="true"><ProviderLogo provider={first} className={styles.titleIcon} /></span>{firstAgent.name}</span> and <span className={styles.titleProduct}><span aria-hidden="true"><ProviderLogo provider={second} className={styles.titleIcon} /></span>{secondAgent.name}</span> together in <span className={styles.titleProduct}><Image src="/alook.svg" alt="" width={36} height={36} className={styles.titleIcon} /><span className={styles.titleBrand}>Alook</span></span></h1>+ <p className={styles.intro}>{guide.description}</p>+ <Prerequisites>+ {firstAgent.preparation} {secondAgent.preparation} Have Node.js and npm installed too.+ Keep that computer online while your bots work.{" "}+ Setup: <a href={firstAgent.setupUrl}>{firstAgent.setupName}</a> and <a href={secondAgent.setupUrl}>{secondAgent.setupName}</a>.+ </Prerequisites>+ </header>+ <details className={styles.mobileContents}><summary>On this page<ChevronDown size={14} /></summary><Contents steps={steps} /></details>+ <section id="sign-in" className={styles.step}>+ <Heading index={0} steps={steps} />+ <p>Open <ZoneLink href="/sign-in" zone="blog">Alook</ZoneLink> and sign in. If you are new, use the same screen to create your account. <strong>Creating your Alook account is completely free.</strong></p>+ <CompletionCriteria>make sure you can open your <ZoneLink href="/c/me" zone="blog">Alook home</ZoneLink>.</CompletionCriteria>+ </section>+ <section id="connect" className={styles.step}>+ <Heading index={1} steps={steps} />+ <p>{guide.connectLead} Open <ZoneLink href="/c/me/machines" zone="blog">Machines</ZoneLink> and choose <strong>Connect a machine</strong>. Copy the command Alook gives you, then paste it into Terminal on the computer where your agents are installed.</p>+ <ConnectDemo agents={guide.agents} />+ <p>The example uses a placeholder key. Run the command from <em>your</em> Alook screen, then return to <ZoneLink href="/c/me/machines" zone="blog">Machines</ZoneLink> to check the connection.</p>+ <CompletionCriteria>check that your computer appears Online in <ZoneLink href="/c/me/machines" zone="blog">Machines</ZoneLink>.</CompletionCriteria>+ </section>+ <section id={steps[2][0]} className={styles.step}>+ <Heading index={2} steps={steps} />+ <p>{guide.firstBotLead} Open <ZoneLink href="/c/me/bots" zone="blog">My Bots</ZoneLink> and choose <strong>Create a bot</strong>. Give it a name, select your online <strong>Machine</strong>, then select <strong>{first}</strong> under Runtime. {requiresExplicitModel(first) && <>Choose a model from your configured provider under <strong>Model</strong>. </>}Choose <strong>Create bot</strong>.</p>+ <BotsDemo runtime={first} agents={guide.agents} />+ <p>{requiresExplicitModel(first) ? "OpenCode requires a model. The animation uses provider/model-id as a placeholder; select a model available in your own OpenCode configuration." : "Leave Model at its default to use the agent’s own default."} If a runtime is missing, check that it is installed and ready to run on the selected computer before continuing.</p>+ <CompletionCriteria>check that your new bot appears in <ZoneLink href="/c/me/bots" zone="blog">My Bots</ZoneLink> with {first} as its runtime.</CompletionCriteria>+ </section>+ <section id={steps[3][0]} className={styles.step}>+ <Heading index={3} steps={steps} />+ <p>{guide.secondBotLead} In <ZoneLink href="/c/me/bots" zone="blog">My Bots</ZoneLink>, choose <strong>Create a bot</strong> again. Give this bot a different name and select the same online <strong>Machine</strong>. Select <strong>{second}</strong> under Runtime for {secondAgent.name}, then choose <strong>Create bot</strong>.</p>+ <BotsDemo runtime={second} agents={guide.agents} />+ <CompletionCriteria>check that your second bot appears in <ZoneLink href="/c/me/bots" zone="blog">My Bots</ZoneLink> with {second} as its runtime.</CompletionCriteria>+ </section>+ <section id="create-server" className={styles.step}>+ <Heading index={4} steps={steps} />+ <p>{guide.serverLead} Use the <strong>+</strong> in the server sidebar to create a server. Give it a name, then choose <strong>Invite to server</strong>. In the invitation dialog, choose <strong>Invite</strong> next to each bot.</p>+ <ServerDemo agents={guide.agents} />+ <p><strong>Invited</strong> means the invitation was sent. Wait for your bots to join, then open the member list to check that both are there. Send the invites from your own account: you must be the bots’ owner.</p>+ <CompletionCriteria>check that the server’s member list shows you and both bots.</CompletionCriteria>+ </section>+ <section id="send-message" className={styles.step}>+ <Heading index={5} steps={steps} />+ <p>{guide.messageLead}</p>+ <p>For example: “Agree on roles, then wait for my task.”</p>+ <MessageDemo />+ </section>+ <section className={styles.close} aria-label="Continue in Alook">+ <div className={styles.actions}><ZoneLink href="/c" zone="blog" className={styles.cta}>Open Alook<ArrowRight size={16} /></ZoneLink><ZoneLink href="/tutorials" zone="blog">Back to Tutorials</ZoneLink></div>+ </section>+ </article>+ <nav className={styles.contents} aria-label="On this page"><p>On this page</p><Contents steps={steps} /></nav>+ </div>+ </div>;+}diff --git a/src/web/blog/src/app/tutorials/layout.dom.test.tsx b/src/web/blog/src/app/tutorials/layout.dom.test.tsxnew file mode 100644index 000000000..3e3cba3d8--- /dev/null+++ b/src/web/blog/src/app/tutorials/layout.dom.test.tsx@@ -0,0 +1,39 @@+import type { ComponentProps } from "react";+import { describe, expect, it, vi } from "vitest";+import { render, screen, within } from "@/test/react-dom-harness";+import TutorialsLayout from "./layout";++vi.mock("next/link", () => ({+ default: ({ href, children, ...props }: ComponentProps<"a">) => (+ <a data-next-link="true" href={href} {...props}>{children}</a>+ ),+}));+vi.mock("next/image", () => ({+ default: ({ src, alt }: { src: string; alt: string }) => <img src={src} alt={alt} />,+}));++describe("Tutorials layout", () => {+ it("renders its breadcrumb and children with navigation across the correct zone boundaries", () => {+ render(<TutorialsLayout><h1>Tutorial directory</h1></TutorialsLayout>);++ expect(within(screen.getByRole("main")).getByRole("heading", { name: "Tutorial directory" })).toBeVisible();+ const breadcrumb = within(screen.getByRole("navigation", { name: "", exact: true })).getByRole("link", { name: "Tutorials", exact: true });+ expect(breadcrumb).toHaveAttribute("href", "/tutorials");+ expect(breadcrumb).toHaveAttribute("data-next-link", "true");+ expect(screen.getByRole("button", { name: "Toggle theme" })).toBeVisible();+ for (const home of screen.getAllByRole("link", { name: /^Alook(?: Alook)?$/ })) {+ expect(home).toHaveAttribute("href", "/");+ expect(home).not.toHaveAttribute("data-next-link");+ }++ const footer = within(screen.getByRole("contentinfo"));+ const navigation = within(footer.getByRole("navigation", { name: "Footer navigation" }));+ expect(navigation.getAllByRole("link").map((link) => link.getAttribute("href")))+ .toEqual(["/templates", "/blog", "/guides", "/tutorials", "/llms.txt", "/privacy"]);+ expect(navigation.getByRole("link", { name: "Blog", exact: true })).toHaveAttribute("data-next-link", "true");+ for (const name of ["Templates", "llms.txt", "Privacy"]) {+ expect(navigation.getByRole("link", { name, exact: true })).not.toHaveAttribute("data-next-link");+ }+ expect(navigation.getByRole("link", { name: "Guides", exact: true })).toHaveAttribute("data-next-link", "true");+ });+});diff --git a/src/web/blog/src/app/tutorials/layout.tsx b/src/web/blog/src/app/tutorials/layout.tsxnew file mode 100644index 000000000..8bf45ebcc--- /dev/null+++ b/src/web/blog/src/app/tutorials/layout.tsx@@ -0,0 +1,7 @@+import { PublicLayout } from "@/components/public-layout";+import { ThemeToggle } from "@/components/theme-toggle";+import { BlogFooter } from "../blog/blog-footer";++export default function TutorialsLayout({ children }: { children: React.ReactNode }) {+ return <PublicLayout zone="blog" navClassName="max-w-270 px-4 sm:px-6" breadcrumb="Tutorials" rightSlot={<ThemeToggle />} footer={<BlogFooter />}>{children}</PublicLayout>;+}diff --git a/src/web/blog/src/app/tutorials/page.dom.test.tsx b/src/web/blog/src/app/tutorials/page.dom.test.tsxnew file mode 100644index 000000000..c886f67b2--- /dev/null+++ b/src/web/blog/src/app/tutorials/page.dom.test.tsx@@ -0,0 +1,14 @@+import { describe, expect, it, vi } from "vitest";+import { render, screen } from "@/test/react-dom-harness";+import { stepGuides } from "@/lib/step-guides";+import TutorialsPage from "./page";+vi.mock("@/lib/observability/regions", () => ({ ObservedStaticContent: () => null }));+describe("Tutorials directory", () => {+ it("links to the independent tutorial without reusing Guides URLs", () => {+ render(<TutorialsPage />);+ expect(screen.getByRole("heading", { name: "Tutorials", level: 1 })).toBeVisible();+ for (const guide of stepGuides) {+ expect(screen.getByRole("link", { name: new RegExp(guide.title) })).toHaveAttribute("href", `/tutorials/${guide.slug}`);+ }+ });+});diff --git a/src/web/blog/src/app/tutorials/page.tsx b/src/web/blog/src/app/tutorials/page.tsxnew file mode 100644index 000000000..07b3d4344--- /dev/null+++ b/src/web/blog/src/app/tutorials/page.tsx@@ -0,0 +1,22 @@+import { ArrowRight } from "lucide-react";+import { ZoneLink } from "@/components/public-layout";+import { stepGuides } from "@/lib/step-guides";+import { ObservedStaticContent } from "@/lib/observability/regions";+import { buildPublicPageMetadata } from "@/lib/seo/public-page-metadata";++const description = "Step-by-step tutorials to connect your agents and start working together in Alook.";+export const metadata = buildPublicPageMetadata({ title: "Tutorials — Alook", description, path: "/tutorials" });++export default function TutorialsPage() {+ return <div className="mx-auto max-w-270 px-4 pb-24 pt-12 sm:px-6 sm:pt-20">+ <ObservedStaticContent key="/tutorials" pathname="/tutorials" />+ <h1 className="font-sans text-3xl font-semibold tracking-tight sm:text-[2.5rem]">Tutorials</h1>+ <p className="mt-4 max-w-2xl text-muted-foreground">{description}</p>+ <div className="mt-12">+ {stepGuides.map((guide) => <ZoneLink key={guide.slug} href={`/tutorials/${guide.slug}`} zone="blog" className="group flex items-start justify-between gap-8 border-b border-border py-6">+ <div><h2 className="text-xl font-semibold tracking-tight">{guide.title}</h2><p className="mt-2 max-w-2xl text-muted-foreground">{guide.description}</p></div>+ <ArrowRight className="mt-1 shrink-0" size={18} aria-hidden="true" />+ </ZoneLink>)}+ </div>+ </div>;+}diff --git a/src/web/blog/src/components/deferred-blog-failure.dom.test.tsx b/src/web/blog/src/components/deferred-blog-failure.dom.test.tsxnew file mode 100644index 000000000..8c4528986--- /dev/null+++ b/src/web/blog/src/components/deferred-blog-failure.dom.test.tsx@@ -0,0 +1,15 @@+import { describe, expect, it, vi } from "vitest";+import { render, screen } from "@/test/react-dom-harness";+import { BlogFailureBoundary } from "./deferred-blog-failure";+vi.mock("@/components/public-layout", () => ({ ZoneLink: ({ children, href }: { children: React.ReactNode; href: string }) => <a href={href}>{children}</a> }));+function Broken(): React.ReactNode { throw new Error("Chunk unavailable"); }+describe("Blog failure fallback", () => {+ it.each([[true, "Page not found"], [false, "Something went wrong"]] as const)("keeps readable recovery when a visual chunk fails (%s)", (missing, title) => {+ const log = vi.spyOn(console, "error").mockImplementation(() => {});+ try {+ render(<BlogFailureBoundary missing={missing}><Broken /></BlogFailureBoundary>);+ expect(screen.getByRole("heading", { name: title })).toBeVisible();+ expect(screen.getByRole("link", { name: "Go home" })).toHaveAttribute("href", "/");+ } finally { log.mockRestore(); }+ });+});diff --git a/src/web/blog/src/components/deferred-blog-failure.tsx b/src/web/blog/src/components/deferred-blog-failure.tsxnew file mode 100644index 000000000..818df5a77--- /dev/null+++ b/src/web/blog/src/components/deferred-blog-failure.tsx@@ -0,0 +1,35 @@+"use client";++import dynamic from "next/dynamic";+import { Component, type ReactNode } from "react";+import { ZoneLink } from "@/components/public-layout";++function FailureText({ missing = false }: { missing?: boolean }) {+ return <div className="mx-auto flex max-w-xl flex-1 flex-col justify-center gap-6 px-6 py-24">+ <h1 className="text-3xl font-semibold">{missing ? "Page not found" : "Something went wrong"}</h1>+ <p className="text-muted-foreground">{missing ? "Check the address and try again." : "Try again or head back home."}</p>+ <ZoneLink href="/" zone="blog" className="underline underline-offset-4">Go home</ZoneLink>+ </div>;+}++export class BlogFailureBoundary extends Component<{ children: ReactNode; missing?: boolean }, { failed: boolean }> {+ state = { failed: false };+ static getDerivedStateFromError() { return { failed: true }; }+ render() { return this.state.failed ? <FailureText missing={this.props.missing} /> : this.props.children; }+}++const MissingContent = dynamic(() => import("@/components/not-found-content").then((module) => module.NotFoundContent), {+ ssr: false,+ loading: () => <FailureText missing />,+});+const FailedContent = dynamic(() => import("@/components/error-content").then((module) => module.ErrorContent), {+ ssr: false,+ loading: () => <FailureText />,+});++export function DeferredBlogNotFound() {+ return <BlogFailureBoundary missing><MissingContent hardHomeNavigation /></BlogFailureBoundary>;+}+export function DeferredBlogError({ reset }: { reset: () => void }) {+ return <BlogFailureBoundary><FailedContent reset={reset} hardHomeNavigation /></BlogFailureBoundary>;+}diff --git a/src/web/blog/src/components/guides/deferred-demo.dom.test.tsx b/src/web/blog/src/components/guides/deferred-demo.dom.test.tsxnew file mode 100644index 000000000..4fb0d6935--- /dev/null+++ b/src/web/blog/src/components/guides/deferred-demo.dom.test.tsx@@ -0,0 +1,156 @@+import { beforeEach, describe, expect, it, vi } from "vitest";+import { act, render, screen, waitFor, setupUser } from "@/test/react-dom-harness";+import { DeferredDemo } from "./deferred-demo";++const scene = vi.hoisted(() => ({+ create: vi.fn(),+ play: vi.fn(), pause: vi.fn(), restart: vi.fn(), kill: vi.fn(), progress: vi.fn(),+}));+vi.mock("./scenes/connect", () => ({ createScene: scene.create }));+vi.mock("./scenes/bots", () => ({ createScene: scene.create }));+vi.mock("./scenes/server", () => ({ createScene: scene.create }));+vi.mock("./scenes/message", () => ({ createScene: scene.create }));+let reduced = false;+let motionChanged: () => void;+const observers: Array<(entries: { isIntersecting: boolean; intersectionRatio: number }[]) => void> = [];+let intersect: (entries: { isIntersecting: boolean; intersectionRatio: number }[]) => void;+const disconnect = vi.fn();++beforeEach(() => {+ vi.clearAllMocks();+ vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({ top: 100, bottom: 420, height: 320, width: 600, left: 0, right: 600, x: 0, y: 100, toJSON: () => ({}) });+ reduced = false;+ observers.length = 0;+ scene.create.mockReturnValue(scene);+ vi.stubGlobal("matchMedia", () => ({ get matches() { return reduced; }, addEventListener: (_type: string, callback: () => void) => { motionChanged = callback; }, removeEventListener: vi.fn() }));+ vi.stubGlobal("IntersectionObserver", class {+ constructor(callback: typeof intersect, options: IntersectionObserverInit) {+ intersect = callback;+ observers.push(callback);+ expect(options.rootMargin).toBe("0px");+ }+ observe() {}+ disconnect = disconnect;+ });+});++describe("deferred guide demos", () => {+ it("keeps static content until visible, then supports play, offscreen pause, replay and cleanup", async () => {+ const user = setupUser();+ const view = render(<DeferredDemo scene="connect" label="Connection"><p>Static command</p></DeferredDemo>);+ expect(screen.getByText("Static command")).toBeVisible();+ expect(screen.queryByText(/Illustrative demo/)).not.toBeInTheDocument();+ expect(screen.getByRole("group", { name: "Connection playback" })).toBeVisible();+ expect(scene.create).not.toHaveBeenCalled();+ expect(screen.getByRole("button", { name: "Play Connection" })).toBeDisabled();+ await act(async () => intersect([{ isIntersecting: true, intersectionRatio: 1 }]));+ await waitFor(() => expect(scene.create).toHaveBeenCalledOnce());+ await waitFor(() => expect(scene.play).toHaveBeenCalledOnce());+ expect(screen.getByRole("button", { name: "Pause Connection" })).toBeVisible();+ act(() => intersect([{ isIntersecting: false, intersectionRatio: 0 }]));+ expect(scene.pause).toHaveBeenCalled();+ expect(screen.getByRole("button", { name: "Play Connection" })).toBeVisible();+ act(() => intersect([{ isIntersecting: true, intersectionRatio: 1 }]));+ await waitFor(() => expect(scene.play).toHaveBeenCalledTimes(2));+ await user.click(screen.getByRole("button", { name: "Pause Connection" }));+ act(() => intersect([{ isIntersecting: false, intersectionRatio: 0 }]));+ act(() => intersect([{ isIntersecting: true, intersectionRatio: 1 }]));+ expect(scene.play).toHaveBeenCalledTimes(2);+ await user.click(screen.getByRole("button", { name: "Replay Connection" }));+ expect(scene.restart).toHaveBeenCalledOnce();+ view.unmount();+ expect(scene.kill).toHaveBeenCalledOnce();+ expect(disconnect).toHaveBeenCalledOnce();+ });++ it("hands playback to the centered demo on scroll without another intersection event", async () => {+ let tops = { connect: 200, bots: 650 };+ Object.defineProperty(window, "innerHeight", { configurable: true, value: 938 });+ vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function(this: HTMLElement) {+ const sceneId = this.parentElement?.dataset.guideDemo as keyof typeof tops;+ const top = tops[sceneId] ?? 0;+ return { top, bottom: top + 320, height: 320, width: 600, left: 0, right: 600, x: 0, y: top, toJSON: () => ({}) };+ });+ const first = { ...scene, play: vi.fn(), pause: vi.fn() };+ const second = { ...scene, play: vi.fn(), pause: vi.fn() };+ scene.create.mockReturnValueOnce(first).mockReturnValueOnce(second);+ render(<><DeferredDemo scene="connect" label="Connection">Connect</DeferredDemo><DeferredDemo scene="bots" label="Bots">Bots</DeferredDemo></>);+ await act(async () => observers.forEach(callback => callback([{ isIntersecting: true, intersectionRatio: 0.9 }])));+ await waitFor(() => expect(first.play).toHaveBeenCalled());+ expect(second.play).not.toHaveBeenCalled();+ tops = { connect: -70, bots: 380 };+ act(() => window.dispatchEvent(new Event("scroll")));+ await waitFor(() => expect(second.play).toHaveBeenCalled());+ expect(first.pause).toHaveBeenCalled();+ expect(screen.getByRole("button", { name: "Pause Bots" })).toBeVisible();+ });++ it("does not create animation for reduced motion", async () => {+ reduced = true;+ render(<DeferredDemo scene="bots" label="Bots"><p>Both runtimes</p></DeferredDemo>);+ await act(async () => intersect([{ isIntersecting: true, intersectionRatio: 1 }]));+ expect(scene.create).not.toHaveBeenCalled();+ expect(screen.getByText("Both runtimes")).toBeVisible();+ });++ it("retains the static scene if animation setup fails and permits retry", async () => {+ scene.create.mockImplementationOnce(() => { throw new Error("chunk failed"); });+ const user = setupUser();+ render(<DeferredDemo scene="connect" label="Connection"><p>Static command</p></DeferredDemo>);+ await act(async () => intersect([{ isIntersecting: true, intersectionRatio: 1 }]));+ await user.click(await screen.findByRole("button", { name: "Retry animation" }));+ await waitFor(() => expect(scene.create).toHaveBeenCalledTimes(2));+ expect(screen.getByText("Static command")).toBeVisible();+ expect(screen.queryByText(/Illustrative demo/)).not.toBeInTheDocument();+ expect(screen.getByRole("group", { name: "Connection playback" })).toBeVisible();+ });+});+++describe("animation lifecycle changes", () => {+ it.each(["server", "message"] as const)("loads and resumes the %s scene, then replays after completion", async (kind) => {+ const user = setupUser();+ render(<DeferredDemo scene={kind} label="Demo">Static</DeferredDemo>);+ await act(async () => intersect([{ isIntersecting: true, intersectionRatio: 1 }]));+ await waitFor(() => expect(scene.play).toHaveBeenCalled());+ await user.click(screen.getByRole("button", { name: "Pause Demo" }));+ scene.play.mockClear();+ await user.click(screen.getByRole("button", { name: "Play Demo" }));+ expect(scene.play).toHaveBeenCalledOnce();+ act(() => scene.create.mock.calls[0][1]());+ await user.click(screen.getByRole("button", { name: "Play Demo" }));+ expect(scene.restart).toHaveBeenCalledOnce();+ });++ it("returns to static content when reduced motion is enabled and reloads when disabled", async () => {+ const { container } = render(<DeferredDemo scene="connect" label="Demo">Static</DeferredDemo>);+ await act(async () => intersect([{ isIntersecting: true, intersectionRatio: 1 }]));+ await waitFor(() => expect(scene.play).toHaveBeenCalled());+ act(() => { reduced = true; motionChanged(); });+ expect(scene.progress).toHaveBeenCalledWith(0);+ expect(scene.kill).toHaveBeenCalledOnce();+ expect(container.querySelector("figure")).toHaveAttribute("data-demo-status", "static");+ await act(async () => { reduced = false; motionChanged(); });+ await waitFor(() => expect(scene.create).toHaveBeenCalledTimes(2));+ });++ it("rebuilds only on width changes and pauses in a hidden tab", async () => {+ let width = 390;+ vi.spyOn(HTMLElement.prototype, "clientWidth", "get").mockImplementation(() => width);+ render(<DeferredDemo scene="connect" label="Demo">Static</DeferredDemo>);+ act(() => { width = 400; window.dispatchEvent(new Event("resize")); });+ expect(scene.create).not.toHaveBeenCalled();+ await act(async () => intersect([{ isIntersecting: true, intersectionRatio: 1 }]));+ await waitFor(() => expect(scene.play).toHaveBeenCalled());+ act(() => window.dispatchEvent(new Event("resize")));+ expect(scene.kill).not.toHaveBeenCalled();+ await act(async () => { width = 600; window.dispatchEvent(new Event("resize")); });+ await waitFor(() => expect(scene.create).toHaveBeenCalledTimes(2));+ expect(scene.progress).toHaveBeenCalledWith(0);+ expect(scene.kill).toHaveBeenCalledOnce();+ scene.pause.mockClear();+ vi.spyOn(document, "hidden", "get").mockReturnValue(true);+ act(() => document.dispatchEvent(new Event("visibilitychange")));+ expect(scene.pause).toHaveBeenCalled();+ });+});diff --git a/src/web/blog/src/components/guides/deferred-demo.tsx b/src/web/blog/src/components/guides/deferred-demo.tsxnew file mode 100644index 000000000..3d730f5cf--- /dev/null+++ b/src/web/blog/src/components/guides/deferred-demo.tsx@@ -0,0 +1,129 @@+"use client";++import { useEffect, useId, useRef, useState, type ReactNode } from "react";+import { Pause, Play, RotateCcw } from "lucide-react";+import { claimGuidePlayback, refreshGuidePlayback, registerGuidePlayback } from "./playback";+import styles from "./guide.module.css";++type Timeline = { play: () => unknown; pause: () => unknown; restart: () => unknown; kill: () => unknown; progress: (value: number) => unknown };+type SceneModule = { createScene: (root: HTMLElement, complete: () => void) => Timeline };+const loaders: Record<"connect" | "bots" | "server" | "message", () => Promise<SceneModule>> = {+ connect: () => import("./scenes/connect"),+ bots: () => import("./scenes/bots"),+ server: () => import("./scenes/server"),+ message: () => import("./scenes/message"),+};++export function DeferredDemo({ scene, label, children }: { scene: keyof typeof loaders; label: string; children: ReactNode }) {+ const root = useRef<HTMLDivElement>(null);+ const timeline = useRef<Timeline | null>(null);+ const visible = useRef(false);+ const manuallyPaused = useRef(false);+ const ended = useRef(false);+ const load = useRef<() => void>(() => {});+ const id = useId();+ const [status, setStatus] = useState<"static" | "loading" | "ready" | "playing" | "paused" | "ended" | "failed">("static");++ useEffect(() => {+ const element = root.current;+ if (!element) return;+ const motion = window.matchMedia("(prefers-reduced-motion: reduce)");+ let disposed = false;+ let loading = false;+ let generation = 0;+ const pause = () => {+ timeline.current?.pause();+ setStatus((value) => value === "playing" ? "paused" : value);+ };+ load.current = () => {+ if (disposed || !visible.current || motion.matches || loading || timeline.current) return;+ loading = true;+ const request = ++generation;+ setStatus("loading");+ void loaders[scene]().then((module) => {+ if (disposed || request !== generation || motion.matches) return;+ timeline.current = module.createScene(element, () => { ended.current = true; setStatus("ended"); });+ setStatus("ready");+ refreshGuidePlayback();+ }).catch(() => {+ if (!disposed && request === generation) setStatus("failed");+ }).finally(() => { loading = false; });+ };+ const observer = new IntersectionObserver(([entry]) => {+ visible.current = entry.isIntersecting && entry.intersectionRatio >= 0.35;+ if (visible.current) load.current();+ else pause();+ refreshGuidePlayback();+ }, { rootMargin: "0px", threshold: 0.35 });+ observer.observe(element);+ const unregister = registerGuidePlayback(id, { element, pause, select: () => {+ visible.current = true;+ load.current();+ if (timeline.current && !manuallyPaused.current && !ended.current && !motion.matches) {+ timeline.current.play();+ setStatus("playing");+ }+ } });+ const onMotion = () => {+ if (motion.matches) {+ generation++;+ timeline.current?.progress(0);+ timeline.current?.kill();+ timeline.current = null;+ setStatus("static");+ } else load.current();+ };+ let width = element.clientWidth;+ const onResize = () => {+ if (element.clientWidth === width) return;+ width = element.clientWidth;+ if (!timeline.current) return;+ timeline.current.progress(0);+ timeline.current.kill();+ timeline.current = null;+ ended.current = false;+ setStatus("static");+ load.current();+ refreshGuidePlayback();+ };+ window.addEventListener("resize", onResize);+ motion.addEventListener("change", onMotion);+ return () => {+ disposed = true;+ observer.disconnect();+ timeline.current?.kill();+ timeline.current = null;+ unregister();+ motion.removeEventListener("change", onMotion);+ window.removeEventListener("resize", onResize);+ };+ }, [id, scene]);++ function play(restart = false) {+ if (!timeline.current || !visible.current) return;+ manuallyPaused.current = false;+ ended.current = false;+ claimGuidePlayback(id);+ if (restart || status === "ended") timeline.current.restart();+ else timeline.current.play();+ setStatus("playing");+ }++ const enabled = ["ready", "playing", "paused", "ended"].includes(status);+ return (+ <figure className={styles.demo} aria-label={label} data-guide-demo={scene} data-demo-status={status}>+ <noscript><style>{`.${styles.stage}{height:auto!important}.${styles.stage} [data-demo-frame]{position:relative;inset:auto;visibility:visible;opacity:1}.${styles.demoCaption}{display:none}`}</style></noscript>+ <div ref={root} className={styles.stage} aria-hidden="true" inert>{children}</div>+ <div className={styles.demoCaption} role="group" aria-label={`${label} playback`}>+ <div className={styles.controls}>+ {status === "failed" ? <button onClick={() => load.current()}>Retry animation</button> :+ <button disabled={!enabled} aria-label={status === "playing" ? `Pause ${label}` : `Play ${label}`} onClick={() => {+ if (status === "playing") { manuallyPaused.current = true; timeline.current?.pause(); setStatus("paused"); }+ else play();+ }}>{status === "playing" ? <Pause size={14} /> : <Play size={14} />}<span>{status === "playing" ? "Pause" : "Play"}</span></button>}+ <button disabled={!enabled} aria-label={`Replay ${label}`} onClick={() => play(true)}><RotateCcw size={14} /><span>Replay</span></button>+ </div>+ </div>+ </figure>+ );+}diff --git a/src/web/blog/src/components/guides/guide.module.css b/src/web/blog/src/components/guides/guide.module.cssnew file mode 100644index 000000000..7ece55004--- /dev/null+++ b/src/web/blog/src/components/guides/guide.module.css@@ -0,0 +1,118 @@+.page { max-width: 1080px; margin: 0 auto; padding: 40px 24px 80px; font-family: var(--font-sans); }+.breadcrumb { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; color: var(--muted-foreground); font-size: 14px; margin-bottom: 40px; }+.breadcrumb a:hover, .contents a:hover { color: var(--foreground); }+.layout { display: grid; grid-template-columns: minmax(0, 720px) 180px; gap: 64px; align-items: start; }+.article { min-width: 0; }+.header h1 { font-size: clamp(2rem, 3.5vw, 2.75rem); line-height: 1.16; font-weight: 600; letter-spacing: -0.025em; text-wrap: balance; }+.intro { font-size: 18px; line-height: 1.65; margin-top: 24px; max-width: 60ch; color: var(--muted-foreground); text-wrap: pretty; }+.prerequisites { margin-top: 32px; font-size: 14px; line-height: 1.7; color: var(--muted-foreground); }+.prerequisites strong { color: var(--foreground); font-weight: 500; }+.article a:not(.cta) { text-underline-offset: 4px; }+.article p a, .prerequisites a { text-decoration: underline; }+.contents { position: sticky; top: 96px; padding-top: 8px; font-size: 13px; }+.contents p { font-weight: 500; margin-bottom: 16px; }+.contents ol { list-style: none; display: grid; gap: 16px; color: var(--muted-foreground); }+.contents a { display: block; line-height: 1.5; }+.mobileContents { display: none; }+.step { margin-top: 80px; padding-left: 48px; scroll-margin-top: 96px; }+.stepHeading { position: relative; margin-bottom: 24px; }+.stepHeading > span { position: absolute; left: -48px; top: 50%; transform: translateY(-50%); width: 24px; text-align: center; color: var(--muted-foreground); font-size: 16px; font-variant-numeric: tabular-nums; }+.stepLink { color: inherit; text-decoration: none; }+.stepLink > span { margin-left: 0.4em; color: var(--muted-foreground); opacity: 0; font-weight: 400; }+.stepLink:hover > span, .stepLink:focus-visible > span { opacity: 1; }+.stepLink:focus-visible { outline: 2px solid var(--ring); outline-offset: 4px; border-radius: 2px; }+.step h2 { font-size: 26px; font-weight: 600; line-height: 1.3; letter-spacing: -0.015em; text-wrap: balance; }+.step > p, .close p { font-size: 16px; line-height: 1.75; text-wrap: pretty; max-width: 68ch; }+.step > p + p { margin-top: 16px; }+.step strong { font-weight: 600; }+.demo { container-type: inline-size; position: relative; margin: 64px 0 0; }+.stage { position: relative; height: 58.93cqw; background: var(--background); border-radius: var(--radius-lg); overflow: hidden; }+.stage [data-demo-frame] { position: absolute; inset: 0; padding: 0; visibility: hidden; opacity: 0; display: flex; flex-direction: column; justify-content: center; }+.stage [data-demo-frame]:first-child { visibility: visible; opacity: 1; }+.mock { max-width: 460px; width: 100%; margin: 0 auto; background: var(--background); border: 1px solid var(--border); border-radius: var(--radius-lg); padding: 24px; font-size: 14px; line-height: 1.5; }+.mockTitle { display: flex; align-items: center; gap: 8px; font-size: 18px; font-weight: 600; margin-bottom: 16px; }+.mockSub { color: var(--muted-foreground); font-size: 13px; margin-bottom: 16px; }+.field { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 8px 0; }+.fieldValue { display: inline-flex; align-items: center; justify-content: space-between; gap: 16px; border: 1px solid var(--input); border-radius: var(--radius-md); padding: 6px 8px; min-width: 52%; font-size: 13px; }+.mockButton { background: var(--primary); color: var(--primary-foreground); border-radius: var(--radius-md); display: block; text-align: center; padding: 8px 16px; margin-top: 16px; }+.mockInput { border: 1px solid var(--input); padding: 8px; border-radius: var(--radius-md); color: var(--muted-foreground); }+.mockFooter { display: flex; justify-content: flex-end; align-items: center; gap: 16px; margin-top: 16px; }+.mockFooter .mockButton { margin: 0; }+.terminal { max-width: 560px; width: 100%; margin: auto; font-family: var(--font-mono); border: 1px solid var(--border); border-radius: var(--radius-lg); background: var(--background); }+.terminalHeader { padding: 12px 16px; border-bottom: 1px solid var(--border); color: var(--muted-foreground); font-size: 12px; display: flex; align-items: center; gap: 8px; }+.command { white-space: pre-wrap; overflow-wrap: anywhere; font-family: var(--font-mono); font-size: 14px; line-height: 1.8; padding: 24px; }+.prompt { color: var(--muted-foreground); user-select: none; }+.online { display: inline-flex; align-items: center; gap: 6px; color: var(--foreground); font-size: 12px; }+.online svg { color: var(--status-online); }+.botRow { display: flex; align-items: center; gap: 12px; padding: 12px 0; }+.botRow + .botRow { border-top: 1px solid var(--border); }+.botIcon { height: 32px; width: 32px; border-radius: var(--radius-md); background: var(--muted); display: grid; place-items: center; flex: 0 0 auto; }+.botRow small { display: block; color: var(--muted-foreground); font-size: 12px; }+.demoCaption { position: absolute; top: -48px; right: 12px; z-index: 1; }+.controls { display: flex; flex-shrink: 0; gap: 4px; }+.controls button { display: inline-flex; gap: 6px; align-items: center; min-height: 32px; padding: 0 6px; font-size: 12px; font-weight: 400; border-radius: var(--radius-sm); color: var(--muted-foreground); cursor: pointer; }+.controls button:hover:not(:disabled) { background: var(--muted); }+.controls button:disabled { color: var(--muted-foreground); cursor: default; opacity: 0.55; }+.staticDemo { margin-top: 24px; padding: 32px; background: var(--muted); border-radius: var(--radius-lg); }+.invite { display: grid; gap: 16px; }+.invite p { font-size: 14px; }+.inviteUrl { font-family: var(--font-mono); overflow-wrap: anywhere; font-size: 12px; background: var(--muted); padding: 12px; border-radius: var(--radius-sm); }+.close { margin-top: 64px; padding-top: 32px; border-top: 1px solid var(--border); }+.close h2 { font-size: 24px; font-weight: 600; margin-bottom: 16px; }+.sample { margin: 24px 0; padding-left: 24px; border-left: 1px solid var(--border); font-size: 16px; line-height: 1.75; }+.actions { display: flex; align-items: center; gap: 24px; margin-top: 32px; font-size: 14px; }+.cta { display: inline-flex; align-items: center; gap: 16px; padding: 12px 24px; border-radius: var(--radius-md); background: var(--primary); color: var(--primary-foreground); font-weight: 500; }+.cta:hover { opacity: 0.9; }+.page a:focus-visible, .page button:focus-visible, .page summary:focus-visible { outline: 2px solid var(--ring); outline-offset: 4px; }+@media (max-width: 1023px) {+ .layout { display: block; max-width: 720px; margin: 0 auto; }+ .contents { display: none; }+ .mobileContents { display: block; margin-top: 32px; font-size: 14px; }+ .mobileContents summary { cursor: pointer; min-height: 44px; display: flex; align-items: center; gap: 8px; }+ .mobileContents ol { padding: 8px 0 8px 24px; display: grid; gap: 16px; list-style: decimal; }+}+@media (max-width: 639px) {+ .page { padding: 24px 16px 64px; }+ .breadcrumb { margin-bottom: 32px; }+ .intro { font-size: 17px; margin-top: 16px; }+ .step { margin-top: 56px; padding-left: 32px; }+ .stepHeading > span { left: -32px; width: 16px; }+ .step h2 { font-size: 23px; }+ .stage { height: 320px; --motion-sheet-width: 360px; }++ .mock { padding: 16px; }+ .field { gap: 8px; font-size: 13px; }+ .fieldValue { min-width: 0; max-width: 65%; font-size: 12px; }+ .staticDemo { padding: 24px 16px; }+ .command { padding: 16px; font-size: 14px; }+ .controls { gap: 0; }+ .controls button { min-height: 44px; min-width: 44px; justify-content: center; }+ .controls button span { display: none; }+ .actions { gap: 16px; }+}++.mockOutline { border: 1px solid var(--border); border-radius: var(--radius-md); text-align: center; padding: 8px 16px; margin-top: 16px; }++.pointer { position: absolute; top: 0; left: 0; z-index: 2; pointer-events: none; filter: drop-shadow(0 2px 2px #0003); transform-origin: 0 0; }+.keycapSlot { margin-left: auto; display: grid; }+.keycap { grid-area: 1 / 1; justify-self: end; border: 1px solid var(--border); padding: 2px 6px; border-radius: 4px; opacity: 0; visibility: hidden; }+.textCaret { display: inline-block; height: 1em; border-left: 2px solid var(--foreground); vertical-align: -0.15em; }+@media (prefers-reduced-motion: reduce) {+ .demo .stage { height: auto !important; }+ .stage [data-demo-frame] { position: relative; inset: auto; visibility: visible; opacity: 1; }+ .demoCaption { display: none; }+}++.completionCriteria { display: flex; gap: 12px; margin-top: 24px; padding: 16px; border-radius: var(--radius-md); background: var(--muted); color: var(--muted-foreground); font-size: 14px; line-height: 1.6; }+.completionCriteria > span { flex-shrink: 0; }+.completionCriteria p { margin: 0; }++.completionCriteria a { text-decoration: underline; text-underline-offset: 3px; }++.messageComposer { position: relative; width: var(--motion-sheet-width, 640px); max-width: 100%; }+.mentionMenu { position: absolute; z-index: 5; bottom: 100%; left: 48px; width: 256px; padding: 4px; border: 1px solid var(--border); border-radius: var(--radius-lg); background: var(--popover); color: var(--popover-foreground); box-shadow: var(--e2); }+.messageResult { width: var(--motion-sheet-width, 640px); max-width: 100%; margin-bottom: 16px; }++.titleProduct { display: inline-flex; align-items: center; gap: 0.1em; margin-inline: 0.12em; white-space: nowrap; vertical-align: baseline; }+.titleIcon { display: inline-block; width: 0.78em; height: 0.78em; vertical-align: -0.05em; flex-shrink: 0; }+.titleBrand { font-family: var(--font-brand); font-weight: 900; font-size: 1.1em; line-height: 1; }diff --git a/src/web/blog/src/components/guides/message-demo.tsx b/src/web/blog/src/components/guides/message-demo.tsxnew file mode 100644index 000000000..dad0d5fa7--- /dev/null+++ b/src/web/blog/src/components/guides/message-demo.tsx@@ -0,0 +1,62 @@+"use client";++import { useLayoutEffect, useRef, useState } from "react";+import { MousePointer2 } from "lucide-react";+import { ChannelHeader } from "@/components/community/channels/channel-header";+import { ComposerView } from "@/components/community/messages/composer-view";+import { MentionRow } from "@/components/community/messages/composer-suggestion-popups";+import { Message } from "@/components/community/messages/message";+import { EMPTY_MENTION_STATE, type MentionItem } from "@/lib/community/mention-extension";+import { EMPTY_CHANNEL_REF_STATE } from "@/lib/community/channel-ref-extension";+import { CommunityPreviewProfileOwner } from "@/stores/community/profile-preview";+import type { CommunityProfile } from "@/lib/community/models/people";+import type { RenderMsg } from "@/lib/community/models/message";+import { TutorialServerShell } from "./server-demo";+import { DeferredDemo } from "./deferred-demo";+import styles from "./guide.module.css";++const ignore = () => {};+export const tutorialTask = "Agree on roles, then wait for my task.";+const bots: MentionItem[] = ["Milo", "Nova"].map((name, index) => ({ kind: "member", id: `tutorial-${name.toLowerCase()}`, userId: `tutorial-${name.toLowerCase()}`, label: `${name}#100${index + 1}`, name, discriminator: `100${index + 1}`, avatar: `avatar:beam:${name.toLowerCase()}`, status: "online" }));+const profiles = new Map<string, CommunityProfile>([["gus", { id: "gus", name: "Gus", avatar: "avatar:beam:tutorial-gus" }]]);+const sentMessage: RenderMsg = { id: "tutorial-sent-message", type: "chat", authorId: "gus", authorName: "Gus", authorAvatar: "avatar:beam:tutorial-gus", content: `@Milo#1001 @Nova#1002 ${tutorialTask}`, createdAt: "2026-10-28T04:00:00.000Z", seq: 1, grouped: false };+type DraftState = { mentions: number; text: string; popup: number };++function MessageChannel({ sent = false }: { sent?: boolean }) {+ const root = useRef<HTMLDivElement>(null);+ const fileInput = useRef<HTMLInputElement>(null);+ const [draft, setDraft] = useState<DraftState>({ mentions: 0, text: "", popup: -1 });+ useLayoutEffect(() => {+ const element = root.current!;+ const update = (event: Event) => setDraft(value => ({ ...value, ...(event as CustomEvent).detail }));+ element.addEventListener("tutorial-draft", update);+ return () => element.removeEventListener("tutorial-draft", update);+ }, []);+ const hasText = draft.mentions > 0 || Boolean(draft.text);+ return <TutorialServerShell server><CommunityPreviewProfileOwner profiles={profiles}>+ <ChannelHeader channel="general" kind="text" rightPanel={null} onToggle={ignore} />+ <div ref={root} data-message-channel className="flex min-h-0 flex-1 flex-col justify-end">+ {sent && <div className={styles.messageResult} data-message-result><Message m={sentMessage} onOpenThread={ignore} /></div>}+ <div className={styles.messageComposer} data-message-composer data-tutorial-panel>+ {bots.map((bot, index) => <div key={bot.id} data-mention-choice={index} className={styles.mentionMenu} style={{ visibility: draft.popup === index ? "visible" : "hidden" }}><MentionRow item={bot} selected showMembersHeader={false} onSelect={ignore} /></div>)}+ <ComposerView isForumThreadBody={false} dragging={false} onDragEnter={ignore} onDragLeave={ignore} onDragOver={ignore} onDrop={ignore}+ mentionPopup={EMPTY_MENTION_STATE} mentionPresentation={{ status: "ready" }} channelRefPopup={EMPTY_CHANNEL_REF_STATE}+ pendingFiles={[]} removePendingFile={ignore} fileInputRef={fileInput} onFileSelect={ignore} editor={null}+ hideAttach={false} hideEmoji={false} showSend={hasText} sendDisabled={!hasText} onSend={ignore} onUploadFile={ignore} onEmojiPick={ignore}+ editorContent={<div className="min-h-6 text-base chat-input-line-height" data-tutorial-editor>+ {!hasText && <span className="text-muted-foreground">Message /general</span>}+ {bots.slice(0, draft.mentions).map(bot => <span key={bot.id}><span className="mention-highlight">@{bot.label.replace(/#\d+$/, "")}</span>{" "}</span>)}+ <span data-draft-text>{draft.text}</span>{hasText && <span className={styles.textCaret} data-message-caret />}+ </div>} />+ </div>+ </div>+ </CommunityPreviewProfileOwner></TutorialServerShell>;+}++export function MessageDemo() {+ return <DeferredDemo scene="message" label="Send your first message">+ <div data-demo-frame data-motion-center-y><MessageChannel /></div>+ <div data-demo-frame data-motion-center-y><MessageChannel sent /></div>+ <MousePointer2 className={styles.pointer} data-demo-pointer size={30} fill="var(--background)" />+ </DeferredDemo>;+}diff --git a/src/web/blog/src/components/guides/mock-scenes.tsx b/src/web/blog/src/components/guides/mock-scenes.tsxnew file mode 100644index 000000000..e937b5d73--- /dev/null+++ b/src/web/blog/src/components/guides/mock-scenes.tsx@@ -0,0 +1,102 @@+"use client";++import { MousePointer2, Terminal } from "lucide-react";+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";+import { LandingShellMotion, PrototypeSheet, BotCard } from "@/components/home/landing-shell-motion";+import { CommunityPreviewNavigation } from "@/components/community/shell/community-preview-navigation";+import { PairMachineSteps } from "@/components/community/machines/pair-machine-sheet";+import { MachineCard } from "@/components/community/machines/machine-card";+import { BotFormFields } from "@/components/community/bots/bot-form-fields";+import { BotRuntimeFields } from "@/components/community/bots/bot-runtime-fields";+import { BotMachineField } from "@/components/community/bots/bot-machine-field";+import { Button } from "@/components/ui/button";+import { SheetHeader, SheetBody, SheetFooter } from "@/components/ui/sheet";+import { requiresExplicitModel } from "@alook/shared";+import type { CommunityMachineSummary } from "@alook/shared";+import { defaultTutorialPair, tutorialAgents, type TutorialPair, type TutorialRuntime } from "@/lib/step-guides";+import { DeferredDemo } from "./deferred-demo";+import styles from "./guide.module.css";++const pairingCommand = "npx --yes @alook/daemon@latest daemon start --machine-key <YOUR_MACHINE_KEY>";+export const tutorialModel = "provider/model-id";+const ignore = () => {};+const machine: CommunityMachineSummary = {+ id: "tutorial-machine", hostname: "studio-mac", displayName: "Studio Mac", platform: "darwin", arch: "arm64", osRelease: "15.6", daemonVersion: "0.1.60",+ status: "online", lastSeenAt: "2026-10-27T12:00:00Z", createdAt: "2026-10-27T12:00:00Z", updatedAt: "2026-10-27T12:00:00Z",+ availableRuntimes: [{ id: "codex", status: "healthy" }, { id: "claude", status: "healthy" }],+};++function Pointer() {+ return <MousePointer2 className={styles.pointer} data-demo-pointer size={30} fill="var(--background)" />;+}++function HomeScreen({ page, children }: { page: "Machines" | "My Bots"; children: ReactNode }) {+ return <CommunityPreviewNavigation value={true}><LandingShellMotion userAvatar="avatar:beam:tutorial-gus" scene={page === "Machines" ? "machine" : "provider"} beat={0}>{children}</LandingShellMotion></CommunityPreviewNavigation>;+}++function MachineList() {+ return <div className="flex flex-1 flex-col gap-6 p-6"><header className="flex items-center justify-between"><div className="text-xl font-medium">Machines</div><Button data-connect-entry>Connect a machine</Button></header></div>;+}++function ConnectSheet() {+ const root = useRef<HTMLDivElement>(null);+ useLayoutEffect(() => { root.current?.querySelector('[aria-label="Copy command"]')?.setAttribute("data-copy", ""); }, []);+ return <HomeScreen page="Machines"><MachineList /><PrototypeSheet label="Connect a machine">+ <SheetHeader><div className="text-lg font-semibold">Connect a machine</div></SheetHeader>+ <SheetBody><div ref={root}><PairMachineSteps command={pairingCommand} generating={false} onCopy={ignore} connectedHostname={null} headingAs="div" /></div></SheetBody>+ <SheetFooter><Button variant="secondary">Done</Button></SheetFooter>+ </PrototypeSheet></HomeScreen>;+}++export function ConnectDemo({ agents = defaultTutorialPair }: { agents?: TutorialPair }) {+ return <DeferredDemo scene="connect" label="Connect your computer">+ <div data-demo-frame><HomeScreen page="Machines"><MachineList /></HomeScreen></div>+ <div data-demo-frame><ConnectSheet /></div>+ <div data-demo-frame><div className={styles.terminal}>+ <div className={styles.terminalHeader} data-terminal-header><Terminal size={14} />Terminal · your computer<span className={styles.keycapSlot}><span className={styles.keycap} data-paste-key>⌘ V</span><span className={styles.keycap} data-enter-key>Enter ↵</span></span></div>+ <pre className={styles.command} data-command><span className={styles.prompt}>$ </span><span data-command-text>{pairingCommand}</span><span data-terminal-newline>{"\n"}</span><span className={styles.textCaret} data-terminal-caret /></pre>+ </div></div>+ <div data-demo-frame><HomeScreen page="Machines"><div className="flex flex-1 flex-col gap-6 p-6"><div className="text-xl font-medium">Machines</div><MachineCard machine={{ ...machine, availableRuntimes: agents.map(id => ({ id, status: "healthy" })) }} onDelete={ignore} onReconnect={ignore} /></div></HomeScreen></div>+ <Pointer />+ </DeferredDemo>;+}++function BotForm({ runtime, count, agents }: { runtime: TutorialRuntime; count: number; agents: TutorialPair }) {+ const root = useRef<HTMLDivElement>(null);+ const [state, setState] = useState<{ name: string; runtime: TutorialRuntime; model: string | null; modelOpen: boolean }>({ name: "", runtime: agents[0], model: null, modelOpen: false });+ const [menuContainer, setMenuContainer] = useState<HTMLDivElement | null>(null);+ useLayoutEffect(() => {+ const element = root.current!;+ const update = (event: Event) => setState((current) => ({ ...current, ...(event as CustomEvent).detail }));+ element.addEventListener("tutorial-form", update);+ element.querySelector('input[placeholder="Name your bot"]')?.setAttribute("data-name-field", "");+ element.querySelector('[data-testid="bot-machine-picker"] label')?.setAttribute("data-machine", "");+ return () => element.removeEventListener("tutorial-form", update);+ }, []);+ return <HomeScreen page="My Bots"><BotListContent count={count} agents={agents} /><PrototypeSheet label="Create a bot">+ <SheetHeader><div className="text-lg font-semibold">Create a bot</div></SheetHeader>+ <SheetBody><div ref={root} data-bot-form className="flex flex-col gap-6">+ <BotFormFields avatarDraft={{ kind: "procedural", image: `avatar:beam:${runtime}` }} onAvatarChange={ignore} name={state.name} setName={ignore} onShuffle={ignore} description="" setDescription={ignore} />+ <BotMachineField machines={[{ ...machine, availableRuntimes: agents.map(id => ({ id, status: "healthy" })) }]} machineId={machine.id} onChange={ignore} radioName={`tutorial-machine-${runtime}`} />+ <BotRuntimeFields options={agents.map(id => ({ id, unhealthy: false, ...(requiresExplicitModel(id) ? { reasoning: { updateMode: "live_next_turn" as const, models: [{ id: tutorialModel, displayName: "Example model", supportedReasoningEfforts: [] }] } } : {}) }))} runtime={state.runtime} model={state.model} modelMenu={{ open: state.modelOpen, container: menuContainer }} onRuntimeChange={ignore} onModelChange={ignore} radioName={`tutorial-runtime-${runtime}`} motionTargetPrefix="tutorial-runtime" />+ <div ref={setMenuContainer} data-model-menu />+ </div></SheetBody>+ <SheetFooter><Button variant="outline">Cancel</Button><Button data-create-submit disabled={!state.name || (requiresExplicitModel(state.runtime) && !state.model)}>Create bot</Button></SheetFooter>+ </PrototypeSheet></HomeScreen>;+}++export function BotListContent({ count, agents = defaultTutorialPair }: { count: number; agents?: TutorialPair }) {+ return <div className="flex flex-1 flex-col gap-6 p-6"><header className="flex items-center justify-between"><div className="text-xl font-medium">My Bots</div><Button data-bot-entry>Create a bot</Button></header>+ {count > 0 && <BotCard name="Milo" runtime={agents[0]} model={requiresExplicitModel(agents[0]) ? tutorialModel : null} status="Online" />}{count > 1 && <BotCard name="Nova" runtime={agents[1]} model={requiresExplicitModel(agents[1]) ? tutorialModel : null} status="Online" />}+ </div>;+}++export function BotsDemo({ runtime, agents = defaultTutorialPair }: { runtime: TutorialRuntime; agents?: TutorialPair }) {+ const count = runtime === agents[0] ? 0 : 1;+ return <DeferredDemo scene="bots" label={`Create your ${tutorialAgents[runtime].name} bot`}>+ <div data-demo-frame data-bot-runtime={runtime} data-bot-name={count === 0 ? "Milo" : "Nova"} data-initial-runtime={agents[0]}><HomeScreen page="My Bots"><BotListContent count={count} agents={agents} /></HomeScreen></div>+ <div data-demo-frame data-motion-center-y={requiresExplicitModel(runtime) ? "" : undefined}><BotForm runtime={runtime} count={count} agents={agents} /></div>+ <div data-demo-frame><HomeScreen page="My Bots"><BotListContent count={count + 1} agents={agents} /></HomeScreen></div>+ <Pointer />+ </DeferredDemo>;+}diff --git a/src/web/blog/src/components/guides/playback.test.ts b/src/web/blog/src/components/guides/playback.test.tsnew file mode 100644index 000000000..271454c4e--- /dev/null+++ b/src/web/blog/src/components/guides/playback.test.ts@@ -0,0 +1,15 @@+import { describe, expect, it } from "vitest";+import { closestVisibleGuide } from "./playback";++describe("tutorial viewport playback selection", () => {+ it("selects the centered scene when two scenes are visible", () => {+ expect(closestVisibleGuide([{ id: "bots", top: -120, height: 320 }, { id: "server", top: 215, height: 320 }], 938)).toBe("server");+ });+ it("changes owner on scroll even when neither scene crosses the 35% threshold", () => {+ expect(closestVisibleGuide([{ id: "bots", top: 200, height: 320 }, { id: "server", top: 650, height: 320 }], 938)).toBe("bots");+ expect(closestVisibleGuide([{ id: "bots", top: -70, height: 320 }, { id: "server", top: 380, height: 320 }], 938)).toBe("server");+ });+ it("selects no animation when no stage is substantially visible", () => {+ expect(closestVisibleGuide([{ id: "bots", top: -310, height: 320 }, { id: "server", top: 920, height: 320 }], 938)).toBeUndefined();+ });+});diff --git a/src/web/blog/src/components/guides/playback.ts b/src/web/blog/src/components/guides/playback.tsnew file mode 100644index 000000000..eeef18343--- /dev/null+++ b/src/web/blog/src/components/guides/playback.ts@@ -0,0 +1,47 @@+type Candidate = { id: string; top: number; height: number };+export function closestVisibleGuide(candidates: Candidate[], viewportHeight: number) {+ return candidates.filter(({ top, height }) => height > 0 && Math.max(0, Math.min(viewportHeight, top + height) - Math.max(0, top)) / height >= 0.35)+ .sort((a, b) => Math.abs(a.top + a.height / 2 - viewportHeight / 2) - Math.abs(b.top + b.height / 2 - viewportHeight / 2))[0]?.id;+}+type Entry = { element: HTMLElement; select: () => void; pause: () => void };+const entries = new Map<string, Entry>();+let pending: number | null = null;+export function refreshGuidePlayback() {+ if (document.hidden) {+ for (const entry of entries.values()) entry.pause();+ return;+ }+ if (pending !== null) return;+ pending = window.requestAnimationFrame(() => {+ pending = null;+ const selected = document.hidden ? undefined : closestVisibleGuide([...entries].map(([id, { element }]) => {+ const { top, height } = element.getBoundingClientRect();+ return { id, top, height };+ }), window.innerHeight);+ for (const [id, entry] of entries) {+ if (id !== selected) entry.pause();+ }+ if (selected) entries.get(selected)?.select();+ });+}+export function claimGuidePlayback(id: string) {+ for (const [otherId, entry] of entries) if (id !== otherId) entry.pause();+}+export function registerGuidePlayback(id: string, entry: Entry) {+ if (entries.size === 0) {+ window.addEventListener("scroll", refreshGuidePlayback, { passive: true });+ window.addEventListener("resize", refreshGuidePlayback);+ document.addEventListener("visibilitychange", refreshGuidePlayback);+ }+ entries.set(id, entry);+ return () => {+ entries.delete(id);+ if (entries.size === 0) {+ window.removeEventListener("scroll", refreshGuidePlayback);+ window.removeEventListener("resize", refreshGuidePlayback);+ document.removeEventListener("visibilitychange", refreshGuidePlayback);+ if (pending !== null) window.cancelAnimationFrame(pending);+ pending = null;+ } else refreshGuidePlayback();+ };+}diff --git a/src/web/blog/src/components/guides/prerequisites.dom.test.tsx b/src/web/blog/src/components/guides/prerequisites.dom.test.tsxnew file mode 100644index 000000000..b12773ae4--- /dev/null+++ b/src/web/blog/src/components/guides/prerequisites.dom.test.tsx@@ -0,0 +1,9 @@+import { describe, expect, it } from "vitest";+import { render, screen } from "@/test/react-dom-harness";+import { Prerequisites } from "./prerequisites";+describe("Tutorial prerequisites", () => {+ it("provides a named region for each tutorial's requirements", () => {+ render(<Prerequisites>Install and sign in to your agents.</Prerequisites>);+ expect(screen.getByRole("complementary", { name: "Before you begin" })).toHaveTextContent("Install and sign in to your agents.");+ });+});diff --git a/src/web/blog/src/components/guides/prerequisites.tsx b/src/web/blog/src/components/guides/prerequisites.tsxnew file mode 100644index 000000000..000991bf1--- /dev/null+++ b/src/web/blog/src/components/guides/prerequisites.tsx@@ -0,0 +1,9 @@+import type { ReactNode } from "react";+import styles from "./guide.module.css";++export function Prerequisites({ children }: { children: ReactNode }) {+ return <aside className={styles.prerequisites} aria-label="Before you begin">+ <strong>Before you begin</strong>+ <div>{children}</div>+ </aside>;+}diff --git a/src/web/blog/src/components/guides/scenes/bots.ts b/src/web/blog/src/components/guides/scenes/bots.tsnew file mode 100644index 000000000..401ebb2da--- /dev/null+++ b/src/web/blog/src/components/guides/scenes/bots.ts@@ -0,0 +1,54 @@+import { requiresExplicitModel } from "@alook/shared";+import { tutorialModel } from "../mock-scenes";+import { demoMotion } from "./motion";++export function createScene(root: HTMLElement, complete: () => void) {+ const { timeline, frames, click, move, frame, action, zoom } = demoMotion(root, complete);+ const update = (index: number, detail: object) => frames[index].querySelector("[data-bot-form]")!.dispatchEvent(new CustomEvent("tutorial-form", { detail }));+ const { botRuntime: runtime, botName: name, initialRuntime } = root.querySelector<HTMLElement>("[data-bot-runtime]")!.dataset as { botRuntime: string; botName: string; initialRuntime: string };+ timeline.call(() => update(1, { name: "", runtime: initialRuntime, model: null, modelOpen: false }), [], 0);+ const fill = (index: number, runtime: string, name: string, start: number) => {+ const form = frames[index];+ const nameField = form.querySelector("[data-name-field]")!;+ const option = form.querySelector(`[data-motion-target="tutorial-runtime-${runtime}"]`)!;+ const submit = form.querySelector("[data-create-submit]")!;+ zoom(index, start, nameField);+ action(`name-${runtime}`, start + 1);+ click(nameField, start + 1);+ for (let count = 1; count <= name.length; count++) timeline.call(() => update(index, { name: name.slice(0, count) }), [], start + 2.3 + count * 0.18);+ zoom(index, start + 3.5, option);+ action(`runtime-${runtime}`, start + 4.5);+ click(option, start + 4.5);+ timeline.call(() => update(index, { runtime }), [], start + 5.6);+ const modelTime = requiresExplicitModel(runtime) ? 7 : 0;+ if (modelTime) {+ const body = form.querySelector<HTMLElement>('[data-slot="sheet-body"]')!;+ timeline.set(body, { scrollTop: 0 }, 0);+ timeline.to(body, { scrollTop: () => body.scrollHeight - body.clientHeight, duration: 0.6, ease: "power2.inOut" }, start + 5.9);+ const modelTrigger = form.querySelector('[data-testid="bot-model-select"]')!;+ const modelOption = () => Array.from(form.querySelectorAll('[data-model-menu] [role="option"]')).find(option => option.textContent?.includes(tutorialModel))!;+ zoom(index, start + 6.6, modelTrigger);+ action("choose-model", start + 7.6);+ click(modelTrigger, start + 7.6);+ timeline.call(() => update(index, { modelOpen: true }), [], start + 8.7);+ zoom(index, start + 9, () => form.querySelector('[data-model-menu] [data-slot="select-content"]')!);+ click(modelOption, start + 10.4);+ timeline.call(() => update(index, { model: tutorialModel, modelOpen: false }), [], start + 11.6);+ }+ zoom(index, start + 6.6 + modelTime, submit);+ action(`create-${runtime}`, start + 7.6 + modelTime);+ click(submit, start + 7.6 + modelTime);+ };+ const entry = frames[0].querySelector("[data-bot-entry]")!;+ action(`open-create-${runtime}`, 0);+ move(entry, 0.4);+ zoom(0, 1.5, entry);+ click(entry, 2.4);+ frame(0, 1, 3.8);+ fill(1, runtime, name, 4.3);+ const modelTime = requiresExplicitModel(runtime) ? 7 : 0;+ frame(1, 2, 13.6 + modelTime);+ action(`${runtime}-created`, 13.6 + modelTime);+ timeline.to({}, { duration: 3 }, 13.8 + modelTime);+ return timeline;+}diff --git a/src/web/blog/src/components/guides/scenes/connect.ts b/src/web/blog/src/components/guides/scenes/connect.tsnew file mode 100644index 000000000..6d4f9cd90--- /dev/null+++ b/src/web/blog/src/components/guides/scenes/connect.ts@@ -0,0 +1,33 @@+import { demoMotion } from "./motion";++export function createScene(root: HTMLElement, complete: () => void) {+ const { timeline, frames, click, move, frame, action, zoom } = demoMotion(root, complete);+ const command = root.querySelector("[data-command-text]")!;+ const caret = root.querySelector("[data-terminal-caret]")!;+ const newline = root.querySelector("[data-terminal-newline]")!;+ const pasteKey = root.querySelector("[data-paste-key]")!;+ const enterKey = root.querySelector("[data-enter-key]")!;+ const entry = frames[0].querySelector("[data-connect-entry]")!;+ const copy = frames[1].querySelector("[data-copy]")!;+ timeline.set(command, { display: "none" }).set(newline, { display: "none" }).set(caret, { autoAlpha: 1 }).set([pasteKey, enterKey], { autoAlpha: 0 });+ action("open-connect", 0);+ move(entry, 0.4);+ zoom(0, 1.5, entry);+ click(entry, 2.4);+ frame(0, 1, 3.8);+ zoom(1, 4.3, copy);+ action("copy-command", 5.2);+ click(copy, 5.2);+ frame(1, 2, 7.2);+ action("paste-command", 7.7);+ move(root.querySelector("[data-terminal-header]")!, 7.7);+ timeline.to(caret, { autoAlpha: 0, duration: 0.08, repeat: 10, repeatDelay: 0.3, yoyo: true }, 7.5);+ timeline.to(pasteKey, { autoAlpha: 1, duration: 0.1 }, 8.6).set(command, { display: "inline" }, 8.8).to(pasteKey, { autoAlpha: 0, duration: 0.1 }, 9.8);+ action("press-enter", 10.3);+ timeline.to(enterKey, { autoAlpha: 1, duration: 0.1 }, 10.3).to(enterKey, { autoAlpha: 0, duration: 0.1 }, 11.3);+ timeline.set(newline, { display: "inline" }, 10.5);+ frame(2, 3, 12);+ action("machine-online", 12);+ timeline.to({}, { duration: 2.5 }, 12.3);+ return timeline;+}diff --git a/src/web/blog/src/components/guides/scenes/message.ts b/src/web/blog/src/components/guides/scenes/message.tsnew file mode 100644index 000000000..834b151ac--- /dev/null+++ b/src/web/blog/src/components/guides/scenes/message.ts@@ -0,0 +1,46 @@+import { demoMotion } from "./motion";++const task = "Agree on roles, then wait for my task.";++export function createScene(root: HTMLElement, complete: () => void) {+ const { timeline, frames, click, move, frame, action, zoom } = demoMotion(root, complete);+ const channel = frames[0].querySelector('[data-message-channel]')!;+ const editor = frames[0].querySelector('[data-tutorial-editor]')!;+ const choice = (index: number) => frames[0].querySelector(`[data-mention-choice="${index}"]`)!;+ const update = (detail: object) => channel.dispatchEvent(new CustomEvent("tutorial-draft", { detail }));+ timeline.call(() => update({ mentions: 0, text: "", popup: -1 }), [], 0);+ action("open-channel", 0);+ click(frames[0].querySelector('[data-testid="community-channel-row-general"]')!, 0.4);+ zoom(0, 1.5, editor);+ click(editor, 2.4);+ action("mention-milo", 3.7);+ for (const [index, text] of ["@", "@M", "@Mi"].entries()) timeline.call(() => update({ text }), [], 3.8 + index * 0.2);+ timeline.call(() => update({ popup: 0 }), [], 4.5);+ zoom(0, 4.7, choice(0));+ click(choice(0), 5.6);+ timeline.call(() => update({ mentions: 1, text: "", popup: -1 }), [], 6.9);+ zoom(0, 7.1, editor);+ move(editor, 7.9);+ action("mention-nova", 8);+ for (const [index, text] of ["@", "@N", "@No"].entries()) timeline.call(() => update({ text }), [], 8 + index * 0.2);+ timeline.call(() => update({ popup: 1 }), [], 8.7);+ zoom(0, 8.9, choice(1));+ click(choice(1), 9.8);+ timeline.call(() => update({ mentions: 2, text: "", popup: -1 }), [], 11.1);+ zoom(0, 11.3, editor);+ move(editor, 12.1);+ action("write-task", 12.2);+ for (let count = 1; count <= task.length; count++) timeline.call(() => update({ text: task.slice(0, count) }), [], 12.2 + count * 0.07);+ const sendTarget = frames[0].querySelector('[data-message-composer]')!;+ const send = () => sendTarget.querySelector('[aria-label="Send message"]')!;+ zoom(0, 15.3, send);+ action("send-message", 16.2);+ click(send, 16.2);+ frame(0, 1, 17.6);+ action("message-posted", 17.6);+ const result = frames[1].querySelector('[data-message-result]')!;+ zoom(1, 18, result);+ move(result, 18.9);+ timeline.to({}, { duration: 3 }, 19.8);+ return timeline;+}diff --git a/src/web/blog/src/components/guides/scenes/motion.ts b/src/web/blog/src/components/guides/scenes/motion.tsnew file mode 100644index 000000000..af88629cd--- /dev/null+++ b/src/web/blog/src/components/guides/scenes/motion.ts@@ -0,0 +1,48 @@+import { gsap } from "gsap";++export function demoMotion(root: HTMLElement, complete: () => void) {+ const frames = root.querySelectorAll<HTMLElement>("[data-demo-frame]");+ const pointer = root.querySelector<HTMLElement>("[data-demo-pointer]")!;+ let trackedTarget: Element | null = null;+ const timeline = gsap.timeline({ paused: true, onComplete: complete });+ timeline.call(() => { trackedTarget = null; }, [], 0);+ timeline.set(frames, { autoAlpha: 0, scale: 1, x: 0, y: 0, transformOrigin: "top left" }).set(frames[0], { autoAlpha: 1 }).set(pointer, { autoAlpha: 1, x: 30, y: 90, scale: 1 });+ const resolveTarget = (target: Element | (() => Element)) => typeof target === "function" ? target() : target;+ const move = (target: Element | (() => Element), at: number) => {+ const position = () => {+ const base = root.getBoundingClientRect(), rect = resolveTarget(target).getBoundingClientRect();+ return { x: rect.left - base.left + rect.width / 2, y: rect.top - base.top + rect.height / 2 };+ };+ timeline.to(pointer, { x: () => position().x, y: () => position().y, duration: 0.8, ease: "power2.inOut", onComplete: () => { trackedTarget = resolveTarget(target); } }, at);+ };+ const click = (target: Element | (() => Element), at: number) => {+ move(target, at);+ timeline.to(pointer, { scale: 0.78, duration: 0.12 }, at + 0.9).to(pointer, { scale: 1, duration: 0.18 }, at + 1.02);+ };+ const frame = (from: number, to: number, at: number) => timeline.to(frames[from], { autoAlpha: 0, duration: 0.3 }, at).to(frames[to], { autoAlpha: 1, duration: 0.3 }, at);+ const zoom = (index: number, at: number, target: Element | (() => Element)) => {+ const state = { progress: 0 };+ const camera = { scale: 1, x: 0, y: 0 };+ let destination = camera;+ timeline.to(state, { progress: 1, duration: 0.8, ease: "power2.inOut", onStart: () => {+ const element = resolveTarget(target);+ const base = root.getBoundingClientRect(), rect = element.getBoundingClientRect(), frameRect = frames[index].getBoundingClientRect();+ let scale = Math.min(3, 1120 / base.width);+ camera.scale = Number(gsap.getProperty(frames[index], "scale")); camera.x = Number(gsap.getProperty(frames[index], "x")); camera.y = Number(gsap.getProperty(frames[index], "y"));+ if (element.hasAttribute("data-motion-fit-width")) scale = Math.min(scale, (base.width - 24) / (rect.width / camera.scale));+ const panel = element.closest('[data-slot="sheet-content"], [data-slot="dialog-content"], [data-tutorial-panel]')?.getBoundingClientRect() ?? rect;+ const tx = (panel.left + panel.width / 2 - frameRect.left) / camera.scale;+ const ty = (rect.top + rect.height / 2 - frameRect.top) / camera.scale;+ destination = { scale, x: Math.max(base.width * (1 - scale), Math.min(0, base.width / 2 - tx * scale)), y: frames[index].hasAttribute("data-motion-center-y") ? base.height / 2 - ty * scale : Math.max(base.height * (1 - scale), Math.min(0, base.height / 2 - ty * scale)) };+ }, onUpdate: () => {+ const p = state.progress;+ gsap.set(frames[index], { scale: camera.scale + (destination.scale - camera.scale) * p, x: camera.x + (destination.x - camera.x) * p, y: camera.y + (destination.y - camera.y) * p });+ if (trackedTarget === resolveTarget(target) && frames[index].contains(trackedTarget)) {+ const base = root.getBoundingClientRect(), rect = trackedTarget.getBoundingClientRect();+ gsap.set(pointer, { x: rect.left - base.left + rect.width / 2, y: rect.top - base.top + rect.height / 2 });+ }+ } }, at);+ };+ const action = (name: string, at: number) => timeline.set(root, { attr: { "data-demo-action": name } }, at);+ return { timeline, frames, pointer, move, click, frame, action, zoom };+}diff --git a/src/web/blog/src/components/guides/scenes/scenes.dom.test.tsx b/src/web/blog/src/components/guides/scenes/scenes.dom.test.tsxnew file mode 100644index 000000000..423a5dd8e--- /dev/null+++ b/src/web/blog/src/components/guides/scenes/scenes.dom.test.tsx@@ -0,0 +1,134 @@+import { describe, expect, it, vi } from "vitest";+import { act, render, screen } from "@/test/react-dom-harness";+import { stepGuides } from "@/lib/step-guides";+import { ConnectDemo, BotsDemo } from "../mock-scenes";+import { createScene as connectScene } from "./connect";+import { ServerDemo } from "../server-demo";+import { createScene as serverScene } from "./server";+import { createScene as botScene } from "./bots";+vi.mock("../deferred-demo", () => ({ DeferredDemo: ({ children }: { children: React.ReactNode }) => <div data-testid="scene">{children}</div> }));+vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} });++describe("tutorial action sequences", () => {+ it("uses the landing shell and real pairing controls before pasting and returning online", () => {+ render(<ConnectDemo />);+ const root = screen.getByTestId("scene");+ expect(root.querySelectorAll('[data-testid="landing-motion-stage"]')).toHaveLength(3);+ expect(root.querySelector('[data-copy]')).toHaveAttribute("aria-label", "Copy command");+ const timeline = connectScene(root, vi.fn());+ try {+ act(() => { timeline.time(6.6, false); });+ expect(root.dataset.demoAction).toBe("copy-command");+ act(() => { timeline.time(9, false); });+ expect(root.dataset.demoAction).toBe("paste-command");+ expect(root.querySelector<HTMLElement>("[data-command-text]")!.style.display).toBe("inline");+ act(() => { timeline.time(10.8, false); });+ expect(root.querySelector<HTMLElement>("[data-terminal-newline]")!.style.display).toBe("inline");+ act(() => { timeline.time(13, false); });+ expect(root.dataset.demoAction).toBe("machine-online");+ act(() => { timeline.restart().pause().time(0.1, false); });+ expect(root.dataset.demoAction).toBe("open-connect");+ expect(root.querySelector<HTMLElement>("[data-command-text]")!.style.display).toBe("none");+ expect(root.querySelector<HTMLElement>("[data-terminal-newline]")!.style.display).toBe("none");+ expect(root.querySelector<HTMLElement>("[data-demo-pointer]")!.style.visibility).not.toBe("hidden");+ } finally { timeline.kill(); }+ });+ it.each(stepGuides.flatMap(guide => guide.agents.map((runtime, index) => ({ slug: guide.slug, agents: guide.agents, runtime, name: index === 0 ? "Milo" : "Nova", index }))))("$slug creates $name with $runtime and resets on replay", async ({ agents, runtime, name, index }) => {+ render(<BotsDemo runtime={runtime} agents={agents} />);+ const root = screen.getByTestId("scene");+ const forms = root.querySelectorAll('[data-bot-form]');+ expect(forms).toHaveLength(1);+ expect(Array.from(forms[0].querySelectorAll('[data-testid="bot-provider-picker"] input')).map(node => (node as HTMLInputElement).value)).toEqual(agents);+ const result = root.querySelectorAll("[data-demo-frame]")[2];+ expect(result.textContent).toContain("Milo");+ expect(result.textContent).toContain(agents[0]);+ if (index === 1) {+ expect(result.textContent).toContain("Nova");+ expect(result.textContent).toContain(agents[1]);+ }+ expect(root.querySelectorAll('[data-demo-frame]')).toHaveLength(3);+ const timeline = botScene(root, vi.fn());+ try {+ if (runtime === "opencode") {+ await act(async () => { timeline.time(12.9, false); });+ expect(forms[0].querySelector('[data-create-submit]')).toBeNull();+ expect(root.querySelector('[data-create-submit]')).toBeDisabled();+ await act(async () => { timeline.time(13.1, false); });+ expect(forms[0].querySelector('[data-model-menu] [role="option"]')).not.toBeNull();+ await act(async () => { timeline.time(16.1, false); });+ expect(forms[0].querySelector('[data-testid="bot-model-select"]')).toHaveTextContent("provider/model-id");+ expect(root.querySelector('[data-create-submit]')).toBeEnabled();+ }+ await act(async () => { timeline.time(runtime === "opencode" ? 21 : 14, false); });+ expect(root.dataset.demoAction).toBe(`${runtime}-created`);+ expect(forms[0].querySelector('input[placeholder="Name your bot"]')).toHaveValue(name);+ expect(forms[0].querySelector(`input[value="${runtime}"]`)).toBeChecked();+ act(() => { timeline.restart().pause().time(0.1, false); });+ expect(root.dataset.demoAction).toBe(`open-create-${runtime}`);+ expect(forms[0].querySelector('input[placeholder="Name your bot"]')).toHaveValue("");+ expect(forms[0].querySelector(`input[value="${agents[0]}"]`)).toBeChecked();+ expect(root.querySelector('[data-create-submit]')).toBeDisabled();+ expect(forms[0].querySelector('[data-model-menu] [role="option"]')).toBeNull();+ } finally { timeline.kill(); }+ });+});+++describe("server invitation walkthrough", () => {+ it("creates Studio, directly invites both bots, waits for membership and resets", () => {+ render(<ServerDemo />);+ const root = screen.getByTestId("scene");+ const timeline = serverScene(root, vi.fn());+ try {+ act(() => { timeline.time(7.4, false); });+ expect(root.querySelector<HTMLInputElement>('[data-testid="community-create-server-name"]')!.value).toBe("Studio");+ act(() => { timeline.time(14.5, false); });+ expect(root.querySelector('[data-invite-recipient="milo"] button')!.textContent).toBe("Invited");+ expect(root.querySelector('[data-invite-recipient="nova"] button')!.textContent).toBe("Invite");+ act(() => { timeline.time(17, false); });+ expect(root.querySelector('[data-invite-recipient="nova"] button')!.textContent).toBe("Invited");+ expect(root.dataset.demoAction).toBe("invitations-sent");+ act(() => { timeline.time(24, false); });+ expect(root.dataset.demoAction).toBe("both-joined");+ expect(root.querySelector('[data-members-result]')!.textContent).toContain("Milo");+ expect(root.querySelector('[data-members-result]')!.textContent).toContain("Nova");+ act(() => { timeline.restart().pause().time(0.1, false); });+ expect(root.querySelector<HTMLInputElement>('[data-testid="community-create-server-name"]')!.value).toBe("");+ expect(root.querySelector('[data-invite-recipient="milo"] button')!.textContent).toBe("Invite");+ expect(root.querySelector('[data-invite-recipient="nova"] button')!.textContent).toBe("Invite");+ } finally { timeline.kill(); }+ });+});++describe("server message walkthrough", () => {+ it("selects both native mentions, types, sends and resets the draft on Replay", async () => {+ const { MessageDemo, tutorialTask } = await import("../message-demo");+ const { createScene } = await import("./message");+ render(<MessageDemo />);+ const root = screen.getByTestId("scene");+ const timeline = createScene(root, vi.fn());+ const draft = root.querySelector('[data-message-channel]')!;+ try {+ act(() => { timeline.time(4.6, false); });+ expect(draft.querySelector('[data-draft-text]')).toHaveTextContent("@Mi");+ expect(draft.querySelector<HTMLElement>('[data-mention-choice="0"]')!.style.visibility).toBe("visible");+ act(() => { timeline.time(7, false); });+ expect(draft.querySelector('[data-tutorial-editor]')).toHaveTextContent("@Milo");+ act(() => { timeline.time(8.8, false); });+ expect(draft.querySelector<HTMLElement>('[data-mention-choice="1"]')!.style.visibility).toBe("visible");+ act(() => { timeline.time(11.2, false); });+ expect(draft.querySelectorAll('.mention-highlight')).toHaveLength(2);+ act(() => { timeline.time(15.2, false); });+ expect(draft.querySelector('[data-draft-text]')).toHaveTextContent(tutorialTask);+ expect(draft.querySelector('[aria-label="Send message"]')).toBeEnabled();+ act(() => { timeline.time(18, false); });+ expect(root.dataset.demoAction).toBe("message-posted");+ expect(root.querySelector('[data-message-result]')).toHaveTextContent(tutorialTask);+ expect(root.querySelector('[data-message-result]')).toHaveTextContent("Gus");+ act(() => { timeline.restart().pause().time(0.1, false); });+ expect(draft.querySelectorAll('.mention-highlight')).toHaveLength(0);+ expect(draft.querySelector('[data-draft-text]')).toHaveTextContent("");+ expect(root.dataset.demoAction).toBe("open-channel");+ } finally { timeline.kill(); }+ });+});diff --git a/src/web/blog/src/components/guides/scenes/server.ts b/src/web/blog/src/components/guides/scenes/server.tsnew file mode 100644index 000000000..13bf982fe--- /dev/null+++ b/src/web/blog/src/components/guides/scenes/server.ts@@ -0,0 +1,32 @@+import { demoMotion } from "./motion";++export function createScene(root: HTMLElement, complete: () => void) {+ const { timeline, frames, move, click, frame, action, zoom } = demoMotion(root, complete);+ const target = (index: number, selector: string) => frames[index].querySelector(selector)!;+ const update = (element: Element, detail: object, at: number) => timeline.call(() => { element.dispatchEvent(new CustomEvent("tutorial-state", { detail })); }, [], at);+ const form = target(1, "[data-server-form]");+ const invites = target(3, "[data-invite-form]");+ update(form, { name: "" }, 0);+ update(invites, { milo: false, nova: false }, 0);+ const plus = target(0, '[data-testid="community-server-add"]');+ action("create-server", 0); move(plus, 0.4); zoom(0, 1.4, plus); click(plus, 2.3); frame(0, 1, 3.6);+ const name = target(1, '[data-testid="community-create-server-name"]');+ zoom(1, 4, name); click(name, 4.9);+ [..."Studio"].forEach((_, i) => update(form, { name: "Studio".slice(0, i + 1) }, 6 + i * 0.17));+ click(target(1, '[data-testid="community-create-server-submit"]'), 7.5); frame(1, 2, 8.9);+ const invite = target(2, '[aria-label="Invite to server"]');+ action("open-invite", 9); zoom(2, 9.3, invite); click(invite, 10.2); frame(2, 3, 11.6);+ const milo = target(3, '[data-invite-recipient="milo"] button');+ const nova = target(3, '[data-invite-recipient="nova"] button');+ zoom(3, 12, milo); action("invite-milo", 12.9); click(milo, 12.9);+ update(invites, { milo: true }, 14.1);+ action("invite-nova", 15); click(nova, 15);+ update(invites, { nova: true }, 16.2);+ action("invitations-sent", 16.2);+ frame(3, 4, 18.5);+ const members = target(4, '[aria-label="Member list"]');+ zoom(4, 19, members); click(members, 19.9); frame(4, 5, 21.3);+ action("both-joined", 21.3); zoom(5, 21.7, target(5, "[data-members-result]"));+ timeline.to({}, { duration: 3 }, 22.5);+ return timeline;+}diff --git a/src/web/blog/src/components/guides/server-demo.tsx b/src/web/blog/src/components/guides/server-demo.tsxnew file mode 100644index 000000000..cddf0a22f--- /dev/null+++ b/src/web/blog/src/components/guides/server-demo.tsx@@ -0,0 +1,63 @@+"use client";++import { useLayoutEffect, useRef, useState, type ReactNode } from "react";+import { MousePointer2 } from "lucide-react";+import { LandingShellMotion, PrototypeComposer, PrototypeInviteSurface } from "@/components/home/landing-shell-motion";+import { sceneSnapshot } from "@/components/home/landing-shell-motion-timeline";+import { CommunityPreviewNavigation } from "@/components/community/shell/community-preview-navigation";+import { CreateServerDialog } from "@/components/community/settings/create-server-dialog";+import { ChannelHeader } from "@/components/community/channels/channel-header";+import { MemberIdentityRow } from "@/components/community/members/member-identity-row";+import { InviteFriendRow } from "@/components/community/social/invite-dialog";+import type { Server } from "@/lib/community/models/navigation";+import type { DM } from "@/lib/community/models/people";+import { defaultTutorialPair, type TutorialPair } from "@/lib/step-guides";+import { BotListContent } from "./mock-scenes";+import { DeferredDemo } from "./deferred-demo";+import styles from "./guide.module.css";++const ignore = () => {};+const inviteLink = "https://alook.ai/c/invite/EXAMPLE";+const dms: DM[] = ["Milo", "Nova"].map((name, index) => ({ id: `tutorial-dm-${name.toLowerCase()}`, userId: `tutorial-${name.toLowerCase()}`, name, discriminator: `100${index + 1}`, avatar: `avatar:beam:${name.toLowerCase()}`, avatarVersion: 0, status: "online", preview: "Available" }));+const createdServers: Server[] = [{ id: "gus", name: "Gus", initial: "G", active: false, unread: false, mentions: 0, isOwner: true, icon: null }, { id: "work", name: "Studio", initial: "S", active: true, unread: false, mentions: 0, isOwner: true, icon: null }];+const base = sceneSnapshot("provider", 0);+export function TutorialServerShell({ server = false, activeDm, children }: { server?: boolean; activeDm?: string; children?: ReactNode }) {+ return <CommunityPreviewNavigation value={true}><LandingShellMotion userAvatar="avatar:beam:tutorial-gus" scene={server ? "server" : "provider"} beat={0} previewServers={server || activeDm ? createdServers : undefined} dms={dms} activeDm={activeDm}>{children}</LandingShellMotion></CommunityPreviewNavigation>;+}+function useSceneState<T extends object>(initial: T) {+ const ref = useRef<HTMLDivElement>(null);+ const [state, setState] = useState(initial);+ useLayoutEffect(() => {+ const element = ref.current!;+ const update = (event: Event) => setState((value) => ({ ...value, ...(event as CustomEvent).detail }));+ element.addEventListener("tutorial-state", update);+ return () => element.removeEventListener("tutorial-state", update);+ }, []);+ return { ref, state };+}+function CreateServer({ agents }: { agents: TutorialPair }) {+ const { ref, state } = useSceneState({ name: "" });+ return <TutorialServerShell><BotListContent count={2} agents={agents} /><div ref={ref} data-server-form><CreateServerDialog onClose={ignore} previewName={state.name} /></div></TutorialServerShell>;+}+function ServerContent({ joined = false }: { joined?: boolean }) {+ return <><ChannelHeader channel="general" kind="text" rightPanel={joined ? "members" : null} onToggle={ignore} />+ <div className="flex min-h-0 flex-1">+ <div className="flex min-w-0 flex-1 flex-col"><div className="flex-1" /><PrototypeComposer snapshot={base} target="server-composer" placeholder="Message /general" /></div>+ {joined && <aside className="w-60 shrink-0 border-l border-border/50 p-4"><div data-members-result><div className="mb-4 text-xs font-medium text-muted-foreground">Online — 3</div><div className="flex flex-col gap-5"><MemberIdentityRow name="Gus" avatarLabel="Gus" avatarSeed="gus" presence="online" />{dms.map(dm => <MemberIdentityRow key={dm.id} name={dm.name} discriminator={dm.discriminator} avatarLabel={dm.name} avatarSeed={dm.userId} avatarSrc={dm.avatar} presence="online" />)}</div></div></aside>}+ </div></>;+}+function Invite() {+ const { ref, state } = useSceneState({ milo: false, nova: false });+ return <TutorialServerShell server><ServerContent /><div ref={ref} data-invite-form><PrototypeInviteSurface snapshot={{ ...base, inviteOpen: true }} serverName="Studio" inviteLink={inviteLink}>{dms.map((dm, index) => <div key={dm.id} data-invite-recipient={index === 0 ? "milo" : "nova"}><InviteFriendRow friend={{ ...dm, sub: "Your bot" }} tokenReady inviting={false} invited={index === 0 ? state.milo : state.nova} onInvite={ignore} /></div>)}</PrototypeInviteSurface></div></TutorialServerShell>;+}+export function ServerDemo({ agents = defaultTutorialPair }: { agents?: TutorialPair }) {+ return <DeferredDemo scene="server" label="Bring them into a server">+ <div data-demo-frame><TutorialServerShell><BotListContent count={2} agents={agents} /></TutorialServerShell></div>+ <div data-demo-frame><CreateServer agents={agents} /></div>+ <div data-demo-frame><TutorialServerShell server><ServerContent /></TutorialServerShell></div>+ <div data-demo-frame><Invite /></div>+ <div data-demo-frame><TutorialServerShell server><ServerContent /></TutorialServerShell></div>+ <div data-demo-frame><TutorialServerShell server><ServerContent joined /></TutorialServerShell></div>+ <MousePointer2 className={styles.pointer} data-demo-pointer size={30} fill="var(--background)" />+ </DeferredDemo>;+}diff --git a/src/web/blog/wrangler.toml b/src/web/blog/wrangler.tomlindex 80bea3856..c67ac3b21 100644--- a/src/web/blog/wrangler.toml+++ b/src/web/blog/wrangler.toml@@ -34,6 +34,10 @@ zone_name = "alook.ai"pattern = "alook.ai/guides*"zone_name = "alook.ai"+[[routes]]+pattern = "alook.ai/tutorials*"+zone_name = "alook.ai"+[[routes]]pattern = "alook.ai/og/blog*"zone_name = "alook.ai"diff --git a/src/web/scripts/dev-zone-ingress.mjs b/src/web/scripts/dev-zone-ingress.mjsindex 9f6f9e8c7..2a9630731 100644--- a/src/web/scripts/dev-zone-ingress.mjs+++ b/src/web/scripts/dev-zone-ingress.mjs@@ -6,7 +6,7 @@ export const ZONE_BACKENDS = Object.freeze({blog: Object.freeze({ hostname: "127.0.0.1", port: 3002 }),})-export const BLOG_ROUTE_PREFIXES = Object.freeze(["/blog", "/og/blog", "/guides"])+export const BLOG_ROUTE_PREFIXES = Object.freeze(["/blog", "/og/blog", "/guides", "/tutorials"])export function selectZone(pathname) {return BLOG_ROUTE_PREFIXES.some((prefix) => pathname.startsWith(prefix))diff --git a/src/web/scripts/dev-zone-ingress.test.ts b/src/web/scripts/dev-zone-ingress.test.tsindex be97abb80..45b722fed 100644--- a/src/web/scripts/dev-zone-ingress.test.ts+++ b/src/web/scripts/dev-zone-ingress.test.ts@@ -27,7 +27,7 @@ async function listen(server: http.Server): Promise<number> {describe("development zone selection", () => {it("matches the approved Cloudflare route prefixes exactly", () => {- expect(BLOG_ROUTE_PREFIXES).toEqual(["/blog", "/og/blog", "/guides"])+ expect(BLOG_ROUTE_PREFIXES).toEqual(["/blog", "/og/blog", "/guides", "/tutorials"])expect(["/blog","/blog/post?draft=1",@@ -37,6 +37,7 @@ describe("development zone selection", () => {].map(selectZone)).toEqual(["blog", "blog", "blog", "blog", "blog"])expect(["/guides", "/guides/", "/guides?topic=coding"].map(selectZone)).toEqual(["blog", "blog", "blog"])expect(selectZone("/guides-other")).toBe("blog")+ expect(["/tutorials", "/tutorials/", "/tutorials/codex-and-claude-code"].map(selectZone)).toEqual(["blog", "blog", "blog"])expect(["/", "/Blog", "/og/Blog", "/api/blog", "/_next/app.js"].map(selectZone)).toEqual(["main","main",diff --git a/src/web/scripts/opennext-wrangler-config.test.ts b/src/web/scripts/opennext-wrangler-config.test.tsindex baad220d4..55128a93d 100644--- a/src/web/scripts/opennext-wrangler-config.test.ts+++ b/src/web/scripts/opennext-wrangler-config.test.ts@@ -118,6 +118,9 @@ describe("OpenNext and Wrangler refresh", () => {const blogToml = readRepositoryFile("src/web/blog/wrangler.toml")expect(bindingNames(blogToml)).toEqual(["ASSETS"])+ for (const path of ["blog", "guides", "tutorials", "og/blog"]) {+ expect(blogToml).toContain(`pattern = "alook.ai/${path}*"`)+ }expect(blogToml).toContain('html_handling = "none"')expect(blogToml).toContain("run_worker_first = true")for (const forbidden of [diff --git a/src/web/scripts/verify-zone-output.test.ts b/src/web/scripts/verify-zone-output.test.tsindex 1309dc76a..7c682df61 100644--- a/src/web/scripts/verify-zone-output.test.ts+++ b/src/web/scripts/verify-zone-output.test.ts@@ -13,6 +13,8 @@ const blogRoutes = {}const blogAppPaths = {"/guides/page": "guides.js",+ "/tutorials/page": "tutorials.js",+ "/tutorials/[slug]/page": "step-guide.js","/_not-found/page": "not-found.js","/blog/(index)/page": "index.js","/blog/[slug]/page": "post.js",@@ -22,6 +24,12 @@ const blogAppPaths = {}describe("zone output verifier", () => {+ it("requires every registered tutorial to be prerendered", () => {+ const fixture = { mainAppPaths: { "/(home)/page": "home.js" }, mainRoutes, blogAppPaths, blogRoutes, blogPrerender: { routes: {} }, postSlugs: [], guideSlugs: ["two-agents"] };+ expect(() => verifyZoneManifests(fixture)).toThrow("missing step guide two-agents");+ expect(() => verifyZoneManifests({ ...fixture, blogPrerender: { routes: { "/tutorials/two-agents": {} } } })).not.toThrow();+ })+it("accepts disjoint main and Blog route inventories", () => {expect(() => verifyZoneManifests({mainAppPaths: { "/(home)/page": "home.js", "/api/health/route": "health.js" },diff --git a/src/web/scripts/verify-zone-output.ts b/src/web/scripts/verify-zone-output.tsindex 937b6d391..52566c724 100644--- a/src/web/scripts/verify-zone-output.ts+++ b/src/web/scripts/verify-zone-output.ts@@ -2,6 +2,8 @@ import { existsSync, readFileSync, readdirSync } from "node:fs"import { basename, join, resolve } from "node:path"import { fileURLToPath } from "node:url"+import { stepGuides } from "../src/lib/step-guides";+type AppPathsManifest = Record<string, string>type RoutesManifest = {redirects: Array<{ source: string; destination: string }>@@ -24,10 +26,11 @@ export function verifyZoneManifests(args: {blogRoutes: RoutesManifestblogPrerender: PrerenderManifestpostSlugs: string[]+ guideSlugs?: string[]}): void {const mainRoutes = Object.keys(args.mainAppPaths)assert(- mainRoutes.every((route) => !route.startsWith("/blog") && !route.startsWith("/og/blog") && !route.startsWith("/guides/")),+ mainRoutes.every((route) => !route.startsWith("/blog") && !route.startsWith("/og/blog") && !route.startsWith("/guides/") && !route.startsWith("/tutorials/")),"Main Next output still owns a Blog route",)assert(@@ -41,6 +44,8 @@ export function verifyZoneManifests(args: {for (const required of ["/blog/(index)/page","/guides/page",+ "/tutorials/page",+ "/tutorials/[slug]/page","/blog/[slug]/page","/blog/feed.xml/route","/og/blog/[slug]/route",@@ -50,7 +55,7 @@ export function verifyZoneManifests(args: {}assert(blogRoutes.every((route) => (- route === "/guides/page" ||+ route === "/guides/page" || route === "/tutorials/page" || route === "/tutorials/[slug]/page" ||route.startsWith("/blog") ||route.startsWith("/og/blog") ||route.startsWith("/internal/blog-discovery") ||@@ -66,6 +71,9 @@ export function verifyZoneManifests(args: {)const prerendered = new Set(Object.keys(args.blogPrerender.routes))+ for (const slug of args.guideSlugs ?? []) {+ assert(prerendered.has(`/tutorials/${slug}`), `Blog output is missing step guide ${slug}`)+ }for (const slug of args.postSlugs) {assert(prerendered.has(`/blog/${slug}`), `Blog output is missing published post ${slug}`)}@@ -98,6 +106,7 @@ export function verifyZoneOutput(webRoot: string): void {blogRoutes: readJson(join(blogNext, "routes-manifest.json")),blogPrerender: readJson(join(blogNext, "prerender-manifest.json")),postSlugs,+ guideSlugs: stepGuides.map((guide) => guide.slug),})assert(!existsSync(join(webRoot, "public/blog")), "Main public tree still contains Blog assets")diff --git a/src/web/src/components/community/bots/bot-machine-field.tsx b/src/web/src/components/community/bots/bot-machine-field.tsxnew file mode 100644index 000000000..d6bbded4a--- /dev/null+++ b/src/web/src/components/community/bots/bot-machine-field.tsx@@ -0,0 +1,76 @@+"use client"++import type { MachineSummary } from "@/hooks/community/use-machines"+import { isPresenceOnline } from "@alook/shared"+import { Label } from "@/components/ui/label"+import { machineName } from "@/lib/community/machine-name"+import { cn } from "@/lib/utils"++export function BotMachineField({ machines, machineId, onChange, error, radioName = "bot-machine" }: {+ machines: MachineSummary[]+ machineId: string+ onChange: (id: string) => void+ error?: string+ radioName?: string+}) {+ return (+ <div className="flex flex-col gap-2">+ <Label className="text-xs text-muted-foreground">Machine</Label>+ {machines.length === 0 ? (+ <p className="text-xs text-muted-foreground">+ No paired machines — pair one first.+ </p>+ ) : (+ <div+ className="flex flex-col gap-2"+ role="radiogroup"+ aria-label="Machine"+ data-testid="bot-machine-picker"+ >+ {machines.map((m) => {+ const online = isPresenceOnline(m.status)+ const selected = machineId === m.id+ return (+ <label+ key={m.id}+ className={cn(+ "flex items-center gap-2 rounded-lg border p-2 cursor-pointer transition-colors",+ selected ? "border-primary bg-primary/5" : "border-border/50 hover:border-foreground/20",+ !online && "opacity-40 pointer-events-none",+ )}+ >+ <input+ type="radio"+ name={radioName}+ value={m.id}+ checked={selected}+ disabled={!online}+ onChange={() => onChange(m.id)}+ className="accent-primary size-3.5"+ />+ <span className="text-sm">{machineName(m)}</span>+ <span+ className={cn(+ "ml-auto inline-flex items-center gap-1 text-xs",+ online ? "text-emerald-600 dark:text-emerald-400" : "text-muted-foreground",+ )}+ >+ <span+ className={cn(+ "inline-block size-1.5 rounded-full",+ online ? "bg-status-online" : "bg-muted-foreground",+ )}+ />+ {online ? "Online" : "Offline"}+ </span>+ </label>+ )+ })}+ </div>+ )}+ {error && (+ <p className="text-xs text-destructive">{error}</p>+ )}+ </div>+ )+}diff --git a/src/web/src/components/community/bots/bot-runtime-fields.tsx b/src/web/src/components/community/bots/bot-runtime-fields.tsxindex ffb2efefe..876a77c16 100644--- a/src/web/src/components/community/bots/bot-runtime-fields.tsx+++ b/src/web/src/components/community/bots/bot-runtime-fields.tsx@@ -36,6 +36,7 @@ export function BotRuntimeFields({modelClassName,runtimeError,modelError,+ modelMenu,disableUnhealthyOptions = false,}: {options: BotRuntimeOption[]@@ -54,6 +55,7 @@ export function BotRuntimeFields({modelClassName?: stringruntimeError?: stringmodelError?: string+ modelMenu?: ComponentProps<typeof ModelField>["menu"]disableUnhealthyOptions?: boolean}) {const selectedRuntime = options.find((option) => option.id === runtime) ?? null@@ -124,7 +126,7 @@ export function BotRuntimeFields({{machineId ? (<MachineModelField key={`${machineId}:${runtime}`} machineId={machineId} runtime={selectedRuntime} value={model} onChange={onModelChange} error={modelError} />) : (- <ModelField runtime={selectedRuntime} value={model} onChange={onModelChange} error={modelError} />+ <ModelField menu={modelMenu} runtime={selectedRuntime} value={model} onChange={onModelChange} error={modelError} />)}<ReasoningEffortFieldruntime={selectedRuntime}diff --git a/src/web/src/components/community/bots/create-bot-sheet.tsx b/src/web/src/components/community/bots/create-bot-sheet.tsxindex 768ffd14a..66ae7f5eb 100644--- a/src/web/src/components/community/bots/create-bot-sheet.tsx+++ b/src/web/src/components/community/bots/create-bot-sheet.tsx@@ -1,4 +1,5 @@"use client"+import { BotMachineField } from "./bot-machine-field"import type { MachineSummary } from "@/hooks/community/use-machines"import { createStore, useAtom, useCreateAtom } from "@tanstack/react-store";@@ -19,7 +20,6 @@ import { machineName } from "@/lib/community/machine-name"import { runtimeLabel } from "@/lib/community/runtime-label"import { CommunitySheet } from "@/components/community/shell/community-sheet"import { Button } from "@/components/ui/button"-import { Label } from "@/components/ui/label"import { type AvatarDraft } from "@/components/avatar"import { serializeBeamSeed } from "@/lib/avatar/seed-url"import { randomBotName } from "@/lib/community/bot-random-name"@@ -33,7 +33,6 @@ import {hasBotCreateFieldErrors,validateBotCreateFields,} from "./bot-form-validation"-import { cn } from "@/lib/utils"import type { BotSummary } from "@/hooks/community/use-bots"// Stable initial seed avoids hydration mismatch (real seed is rerolled on mount).@@ -274,64 +273,7 @@ export function CreateBotSheet({</div>) : (<>- <div className="flex flex-col gap-2">- <Label className="text-xs text-muted-foreground">Machine</Label>- {machines.length === 0 ? (- <p className="text-xs text-muted-foreground">- No paired machines — pair one first.- </p>- ) : (- <div- className="flex flex-col gap-2"- role="radiogroup"- aria-label="Machine"- data-testid="bot-machine-picker"- >- {machines.map((m) => {- const online = isPresenceOnline(m.status)- const selected = machineId === m.id- return (- <label- key={m.id}- className={cn(- "flex items-center gap-2 rounded-lg border p-2 cursor-pointer transition-colors",- selected ? "border-primary bg-primary/5" : "border-border/50 hover:border-foreground/20",- !online && "opacity-40 pointer-events-none",- )}- >- <input- type="radio"- name="bot-machine"- value={m.id}- checked={selected}- disabled={!online}- onChange={() => selectMachine(m.id)}- className="accent-primary size-3.5"- />- <span className="text-sm">{machineName(m)}</span>- <span- className={cn(- "ml-auto inline-flex items-center gap-1 text-xs",- online ? "text-emerald-600 dark:text-emerald-400" : "text-muted-foreground",- )}- >- <span- className={cn(- "inline-block size-1.5 rounded-full",- online ? "bg-status-online" : "bg-muted-foreground",- )}- />- {online ? "Online" : "Offline"}- </span>- </label>- )- })}- </div>- )}- {fieldErrors.machineId && (- <p className="text-xs text-destructive">{fieldErrors.machineId}</p>- )}- </div>+ <BotMachineField machines={machines} machineId={machineId} onChange={selectMachine} error={fieldErrors.machineId} />{selectedMachine && (<div className="flex flex-col gap-2">diff --git a/src/web/src/components/community/bots/model-field-select.dom.test.tsx b/src/web/src/components/community/bots/model-field-select.dom.test.tsxindex 60344fb4b..63e01a728 100644--- a/src/web/src/components/community/bots/model-field-select.dom.test.tsx+++ b/src/web/src/components/community/bots/model-field-select.dom.test.tsx@@ -16,6 +16,24 @@ const runtime = {}describe("ModelField with the real Select", () => {+ it("keeps a controlled preview menu inside its inert container without autofocusing the filter", async () => {+ const host = document.createElement("div");+ host.setAttribute("inert", "");+ document.body.appendChild(host);+ const onChange = vi.fn();+ try {+ const view = render(<ModelField runtime={{ ...runtime, id: "opencode" }} value={null} onChange={onChange} menu={{ open: true, container: host }} />);+ await act(async () => {});+ expect(host.querySelectorAll('[role="option"]')).toHaveLength(3);+ expect(host.querySelector('[data-testid="bot-model-filter-input"]')).not.toBe(document.activeElement);+ expect(onChange).not.toHaveBeenCalled();+ view.rerender(<ModelField runtime={{ ...runtime, id: "opencode" }} value="gemini-3.1-pro-high" onChange={onChange} menu={{ open: false, container: host }} />);+ await act(async () => {});+ expect(screen.getByTestId("bot-model-select")).toHaveTextContent("gemini-3.1-pro-high");+ expect(onChange).not.toHaveBeenCalled();+ view.unmount();+ } finally { host.remove(); }+ });it("notifies discovery only when the actual model popup opens", async () => {const onOpenChange = vi.fn()render(<ModelField runtime={runtime} value={null} onChange={vi.fn()}diff --git a/src/web/src/components/community/bots/model-field.tsx b/src/web/src/components/community/bots/model-field.tsxindex 6a33c25ab..b952338ba 100644--- a/src/web/src/components/community/bots/model-field.tsx+++ b/src/web/src/components/community/bots/model-field.tsx@@ -21,6 +21,7 @@ import {SelectSeparator,} from "@/components/ui/select"import { BotSelectMenuContent, BotSelectMenuItem } from "./bot-select-menu"+import { cn } from "@/lib/utils"import { runtimeLabel } from "@/lib/community/runtime-label"/**@@ -39,12 +40,14 @@ export function ModelField({disabled,error,discovery,+ menu,}: {runtime: Pick<CommunityMachineRuntime, "id" | "reasoning"> | nullvalue: string | nullonChange: (v: string | null) => voiddisabled?: booleanerror?: string+ menu?: { open: boolean; container: HTMLElement | null }discovery?: {isPending: booleanerror: string | null@@ -107,6 +110,8 @@ export function ModelField({<div className="flex flex-col gap-2"><Label className="text-xs text-muted-foreground">{required ? "Model (required)" : "Model"}</Label><Select+ open={menu ? menu.open && Boolean(menu.container) : undefined}+ modal={menu ? false : undefined}items={items}value={required && selectValue === MODEL_SELECT_DEFAULT ? null : selectValue}onValueChange={(next: string | null, details) => {@@ -141,8 +146,10 @@ export function ModelField({<SelectValue placeholder={placeholder} /></SelectTrigger><BotSelectMenuContent+ portalContainer={menu?.container}+ finalFocus={menu ? false : undefined}alignItemWithTrigger={false}- className="flex flex-col overflow-y-hidden *:[[role=listbox]]:flex *:[[role=listbox]]:min-h-0 *:[[role=listbox]]:flex-col"+ className={cn("flex flex-col overflow-y-hidden *:[[role=listbox]]:flex *:[[role=listbox]]:min-h-0 *:[[role=listbox]]:flex-col", menu && "max-h-none")}>{discovery?.isPending && (<p role="status" className="flex shrink-0 items-center gap-2 px-2 py-2 text-xs text-muted-foreground">@@ -169,7 +176,7 @@ export function ModelField({<div data-testid="bot-model-fixed-controls" className="shrink-0 bg-popover"><div className="p-1.5"><Input- autoFocus+ autoFocus={!menu}data-testid="bot-model-filter-input"value={filterQuery}placeholder="Filter models…"diff --git a/src/web/src/components/community/messages/composer-suggestion-popups.tsx b/src/web/src/components/community/messages/composer-suggestion-popups.tsxindex 9c51619f8..8d3b1dfdf 100644--- a/src/web/src/components/community/messages/composer-suggestion-popups.tsx+++ b/src/web/src/components/community/messages/composer-suggestion-popups.tsx@@ -261,7 +261,7 @@ function ChannelRefRow({)}-function MentionRow({+export function MentionRow({item,selected,showMembersHeader,diff --git a/src/web/src/components/community/messages/composer-view.dom.test.ts b/src/web/src/components/community/messages/composer-view.dom.test.tsindex 798535ef7..a70656995 100644--- a/src/web/src/components/community/messages/composer-view.dom.test.ts+++ b/src/web/src/components/community/messages/composer-view.dom.test.ts@@ -85,6 +85,29 @@ function baseProps(}describe("ComposerView", () => {+ it("replaces only editor content for a preview and restores the native editor by default", () => {+ const onSend = vi.fn()+ const props = baseProps({ showSend: true, sendDisabled: false, onSend })+ const view = render(createElement(ComposerView, props))+ expect(view.container.querySelector("[data-editor-content]")).not.toBeNull()+ const input = view.getByTestId(tid.composerInput)+ const send = view.getByTestId(tid.composerSend)+ view.rerender(createElement(ComposerView, {+ ...props,+ editorContent: createElement("p", { "data-preview-draft": "" }, "@Milo Review this plan"),+ }))+ expect(view.container.querySelector("[data-editor-content]")).toBeNull()+ expect(view.getByTestId(tid.composerInput)).toBe(input)+ expect(input.textContent).toBe("@Milo Review this plan")+ expect(view.getByTestId(tid.composerSend)).toBe(send)+ expect(view.getByTestId(tid.composerAttach)).not.toBeNull()+ fireEvent.click(send)+ expect(onSend).toHaveBeenCalledOnce()+ view.rerender(createElement(ComposerView, props))+ expect(view.container.querySelector("[data-preview-draft]")).toBeNull()+ expect(input.querySelector("[data-editor-content]")).not.toBeNull()+ })+it.each([{ name: "native iPhone", native: true, ua: "iPhone", compact: true },{ name: "native Android", native: true, ua: "Android", compact: true },diff --git a/src/web/src/components/community/messages/composer-view.tsx b/src/web/src/components/community/messages/composer-view.tsxindex 3e997ce62..2d808e4bc 100644--- a/src/web/src/components/community/messages/composer-view.tsx+++ b/src/web/src/components/community/messages/composer-view.tsx@@ -2,6 +2,7 @@ import type {ChangeEventHandler,DragEventHandler,RefObject,+ ReactNode,} from "react"import { EditorContent, type Editor } from "@tiptap/react"import {@@ -53,6 +54,7 @@ export type ComposerViewProps = {removePendingFile: (index: number) => voidfileInputRef: RefObject<HTMLInputElement | null>onFileSelect: ChangeEventHandler<HTMLInputElement>+ editorContent?: ReactNodeeditor: Editor | nullhideAttach: booleanhideEmoji: boolean@@ -82,6 +84,7 @@ export function ComposerView({fileInputRef,onFileSelect,editor,+ editorContent,hideAttach,hideEmoji,showSend,@@ -210,10 +213,10 @@ export function ComposerView({}`}data-testid={tid.composerInput}>- <EditorContent+ {editorContent ?? <EditorContenteditor={editor}className={`${isForumThreadBody ? "max-h-60" : "max-h-48"} min-h-6 overflow-y-auto thin-scrollbar text-base chat-input-line-height outline-none`}- />+ />}</div>{!hideAttach && (<buttondiff --git a/src/web/src/components/community/settings/create-dialog-shell.tsx b/src/web/src/components/community/settings/create-dialog-shell.tsxindex 6b1b41404..c19e45a80 100644--- a/src/web/src/components/community/settings/create-dialog-shell.tsx+++ b/src/web/src/components/community/settings/create-dialog-shell.tsx@@ -15,6 +15,7 @@ import { cn } from "@/lib/utils"// opt into a full-weight heading or a different footer alignment when needed.export function CreateDialogShell({open = true,+ preview = false,onClose,title,mutedTitle = true,@@ -23,6 +24,8 @@ export function CreateDialogShell({children,}: {open?: boolean+ /** Noninteractive, inline rendering for product walkthroughs. */+ preview?: booleanonClose: () => voidtitle: React.ReactNodemutedTitle?: boolean@@ -31,21 +34,16 @@ export function CreateDialogShell({footerClassName?: stringchildren: React.ReactNode}) {- return (- <Dialog open={open} onOpenChange={(o) => { if (!o) onClose() }}>- <DialogContent className="w-105 max-w-[calc(100vw-2rem)] p-0">- <DialogHeader className="px-5 pt-5 pb-0">- <DialogTitle className={mutedTitle ? "text-xs font-normal text-muted-foreground" : undefined}>- {title}- </DialogTitle>- </DialogHeader>- {children}- {footer !== undefined && (- <DialogFooter className={cn("mx-0 mb-0 flex-row items-center gap-2 px-5 pb-5", footerClassName ?? "justify-end")}>- {footer}- </DialogFooter>- )}- </DialogContent>- </Dialog>- )+ const content = <>+ <DialogHeader className="px-5 pt-5 pb-0">+ {preview ? <div className={mutedTitle ? "text-xs font-normal text-muted-foreground" : "font-semibold"}>{title}</div> :+ <DialogTitle className={mutedTitle ? "text-xs font-normal text-muted-foreground" : undefined}>{title}</DialogTitle>}+ </DialogHeader>+ {children}+ {footer !== undefined && <DialogFooter className={cn("mx-0 mb-0 flex-row items-center gap-2 px-5 pb-5", footerClassName ?? "justify-end")}>{footer}</DialogFooter>}+ </>+ if (preview) return <div inert data-slot="dialog-content" className="absolute left-1/2 top-1/2 z-20 grid w-(--motion-sheet-width,420px) -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-popover p-0 text-sm text-popover-foreground ring-1 ring-foreground/10">{content}</div>+ return <Dialog open={open} onOpenChange={(o) => { if (!o) onClose() }}>+ <DialogContent className="w-105 max-w-[calc(100vw-2rem)] p-0">{content}</DialogContent>+ </Dialog>}diff --git a/src/web/src/components/community/settings/create-server-dialog.dom.test.tsx b/src/web/src/components/community/settings/create-server-dialog.dom.test.tsxnew file mode 100644index 000000000..837d959f6--- /dev/null+++ b/src/web/src/components/community/settings/create-server-dialog.dom.test.tsx@@ -0,0 +1,40 @@+import React from "react"+import { describe, expect, it, vi } from "vitest"+import { fireEvent, render, screen } from "@/test/react-dom-harness"+import { CreateServerDialog } from "./create-server-dialog"++vi.mock("@/components/avatar", () => ({ SeededBackdrop: () => null }))+vi.mock("../image-crop-dialog", () => ({ ImageCropDialog: () => null }))++describe("CreateServerDialog presentation", () => {+ it("keeps normal creation in a dialog and submits a trimmed name", () => {+ const onCreateServer = vi.fn()+ const onClose = vi.fn()+ const view = render(<CreateServerDialog onClose={onClose} onCreateServer={onCreateServer} />)+ const input = screen.getByRole("textbox", { name: "Server name" })+ expect(screen.getByRole("dialog")).toBeTruthy()+ expect(view.container.contains(input)).toBe(false)+ fireEvent.change(input, { target: { value: " Studio " } })+ fireEvent.click(screen.getByRole("button", { name: "Create server" }))+ expect(onCreateServer).toHaveBeenCalledExactlyOnceWith("Studio", undefined)+ expect(onClose).toHaveBeenCalledTimes(1)+ })++ it("renders controlled preview names inline without taking focus", () => {+ const outside = document.createElement("button")+ document.body.appendChild(outside)+ outside.focus()+ const view = render(<CreateServerDialog onClose={vi.fn()} previewName="Studio" />)+ try {+ const input = view.container.querySelector<HTMLInputElement>('input[aria-label="Server name"]')!+ expect(input.value).toBe("Studio")+ expect(view.container.querySelector('[data-slot="dialog-content"]')?.hasAttribute("inert")).toBe(true)+ expect(document.querySelector('[role="dialog"]')).toBeNull()+ expect(document.activeElement).toBe(outside)+ view.rerender(<CreateServerDialog onClose={vi.fn()} previewName="Studio team" />)+ expect(input.value).toBe("Studio team")+ } finally {+ outside.remove()+ }+ })+})diff --git a/src/web/src/components/community/settings/create-server-dialog.tsx b/src/web/src/components/community/settings/create-server-dialog.tsxindex d60bd0b32..058f45720 100644--- a/src/web/src/components/community/settings/create-server-dialog.tsx+++ b/src/web/src/components/community/settings/create-server-dialog.tsx@@ -59,11 +59,14 @@ function playNameImpact(// The rail's plus button is an explicit create action. Invite links already// own the join journey, so this dialog stays single-purpose and name-first.-export function CreateServerDialog({ onClose, onCreateServer }: {+export function CreateServerDialog({ onClose, onCreateServer, previewName }: {onClose: () => void+ /** Controlled, inert walkthrough state; no portal or focus capture. */+ previewName?: stringonCreateServer?: (name: string, icon?: File) => void}) {- const [name, setName] = useAtom(useCreateAtom(""))+ const [draftName, setName] = useAtom(useCreateAtom(""))+ const name = previewName ?? draftNameconst [iconFile, setIconFile] = useAtom(useCreateAtom<File | null>(null))const [iconPreview, setIconPreview] = useAtom(useCreateAtom<string | null>(null))const [pendingCropSrc, setPendingCropSrc] = useAtom(useCreateAtom<{ src: string; fileName: string } | null>(null))@@ -109,6 +112,7 @@ export function CreateServerDialog({ onClose, onCreateServer }: {return (<><CreateDialogShell+ preview={previewName !== undefined}onClose={onClose}title="Create a server"footer={(@@ -165,7 +169,7 @@ export function CreateServerDialog({ onClose, onCreateServer }: {if (e.key === "Enter" && !e.nativeEvent.isComposing) submit()}}placeholder="My community"- autoFocus+ autoFocus={previewName === undefined}aria-label="Server name"data-testid={tid.createServerName}className="w-full border-0 bg-transparent p-0 text-[26px] font-medium leading-tight tracking-tight shadow-none outline-none placeholder:font-normal placeholder:text-muted-foreground/35 focus-visible:ring-0"diff --git a/src/web/src/components/home/landing-content.test.ts b/src/web/src/components/home/landing-content.test.tsindex c2464cea2..4a0530ad9 100644--- a/src/web/src/components/home/landing-content.test.ts+++ b/src/web/src/components/home/landing-content.test.ts@@ -246,6 +246,7 @@ describe("landing content contract", () => {expect(BRAND_TITLE).toBe("Alook | Multi-Agent Collaboration for Team and Friends")expect(BRAND_DESCRIPTION).toContain("agents you already use")expect(BRAND_DESCRIPTION).toContain("shared rooms")+ expect(LANDING_HERO.subline).toBe("Chat with your team, friends, and agents like Claude Code and Codex in one place. No more relaying messages.")expect(LANDING_META_TITLE).toBe("Alook | Multi-Agent Collaboration for Team and Friends")expect(LANDING_META_DESCRIPTION).toBe("Bring Claude Code and Codex agents into shared chats with Alook. Coordinate multi-agent workflows, share context, and review work with your team.",@@ -374,6 +375,8 @@ describe("landing content contract", () => {expect(navSource).toContain("MARKETING_SITE_LINK_CLASS_NAME")expect(navSource).toContain("MARKETING_SITE_LINK_STYLE")expect(footerSource).toContain("MARKETING_SITE_LINKS.map")+ expect(footerSource).toContain('<a href="/tutorials"')+ expect(navSource).not.toContain('href="/tutorials"')expect(footerSource).toContain("MARKETING_SITE_LINK_CLASS_NAME")expect(footerSource).toContain("MARKETING_SITE_LINK_STYLE")expect(landingStyles).toContain("--landing-content-max: 1320px")@@ -522,7 +525,7 @@ describe("landing content contract", () => {expect(landingPageSource).toContain("Keep your existing setup.")expect(landingPageSource).toContain("styles.ownershipDescription")expect(landingPageSource).not.toContain("The runtime and workspace stay on your paired machine")- expect(`${landingPageSource} ${landingContentSource.split("export const HOME_FAQS")[0]}`).not.toMatch(/\bplaces?\b/i)+ expect(`${landingPageSource} ${landingContentSource.split("export const HOME_FAQS")[0]}`.replace(LANDING_HERO.subline, "")).not.toMatch(/\bplaces?\b/i)expect(landingPageSource).not.toContain("stay in touch")expect(legacyHome).toContain("export function HomePage")})diff --git a/src/web/src/components/home/landing-content.ts b/src/web/src/components/home/landing-content.tsindex 291a620bb..75c5b9c46 100644--- a/src/web/src/components/home/landing-content.ts+++ b/src/web/src/components/home/landing-content.ts@@ -23,7 +23,7 @@ export const LANDING_HERO = {headlineLead: "Multi-Agent Collaboration",headlineTail: "for Team and Friends",subline:- "Bring Claude Code and Codex agents into shared chats. Work with your team without relaying every message.",+ "Chat with your team, friends, and agents like Claude Code and Codex in one place. No more relaying messages.",loggedOutCta: "Get started",loggedInCta: "Open Alook",secondaryCta: "View on GitHub",diff --git a/src/web/src/components/home/landing-footer.tsx b/src/web/src/components/home/landing-footer.tsxindex 2bd476ede..78fd4b922 100644--- a/src/web/src/components/home/landing-footer.tsx+++ b/src/web/src/components/home/landing-footer.tsx@@ -57,6 +57,7 @@ export function LandingFooter() {) : (<Link key={link.href} href={link.href} className={MARKETING_SITE_LINK_CLASS_NAME} style={MARKETING_SITE_LINK_STYLE}>{link.label}</Link>))}+ <a href="/tutorials" className={MARKETING_SITE_LINK_CLASS_NAME} style={MARKETING_SITE_LINK_STYLE}>Tutorials</a></nav></div></footer>diff --git a/src/web/src/components/home/landing-page.module.css b/src/web/src/components/home/landing-page.module.cssindex 0f42ca48b..e0df32af2 100644--- a/src/web/src/components/home/landing-page.module.css+++ b/src/web/src/components/home/landing-page.module.css@@ -1249,7 +1249,11 @@.footerNavigation {display: flex;+ min-width: 0;+ max-width: 100%;+ flex-wrap: wrap;align-items: center;+ justify-content: center;justify-self: center;gap: 24px;}diff --git a/src/web/src/components/home/landing-page.render.test.ts b/src/web/src/components/home/landing-page.render.test.tsindex 6bde5af52..14d73fadc 100644--- a/src/web/src/components/home/landing-page.render.test.ts+++ b/src/web/src/components/home/landing-page.render.test.ts@@ -47,9 +47,10 @@ describe("landing identity profile preview", () => {'data-testid="landing-footer-navigation"',])expect(footer).toContain('aria-label="Footer navigation"')- expect(footer?.match(/href="\/(?:pricing|blog)"/g)).toEqual([+ expect(footer?.match(/href="\/(?:pricing|blog|tutorials)"/g)).toEqual(['href="/pricing"','href="/blog"',+ 'href="/tutorials"',])expect(footer).toContain('href="https://github.com/alookai/alook"')expect(footer).toContain('href="https://discord.com/invite/24PHyEHU3M"')diff --git a/src/web/src/components/home/landing-shell-motion.module.css b/src/web/src/components/home/landing-shell-motion.module.cssindex ae8dea42d..50cf58992 100644--- a/src/web/src/components/home/landing-shell-motion.module.css+++ b/src/web/src/components/home/landing-shell-motion.module.css@@ -146,7 +146,7 @@right: 8px;bottom: 8px;display: flex;- width: 448px;+ width: var(--motion-sheet-width, 448px);flex-direction: column;overflow: hidden;border: 1px solid var(--border);@@ -181,7 +181,7 @@top: 50%;left: 50%;display: flex;- width: 448px;+ width: var(--motion-sheet-width, 448px);max-height: 520px;flex-direction: column;overflow: hidden;diff --git a/src/web/src/components/home/landing-shell-motion.tsx b/src/web/src/components/home/landing-shell-motion.tsxindex dac257146..109605c4f 100644--- a/src/web/src/components/home/landing-shell-motion.tsx+++ b/src/web/src/components/home/landing-shell-motion.tsx@@ -653,11 +653,21 @@ export function LandingShellMotion({machineIntroDescription,overviewDetails = false,beat: controlledBeat,+ children,+ dms,+ activeDm,+ previewServers,+ userAvatar,}: {scene: LandingScenemachineIntroDescription?: stringoverviewDetails?: booleanbeat?: number+ children?: ReactNode+ dms?: DM[]+ activeDm?: string+ previewServers?: Server[]+ userAvatar?: string}) {const [localBeat, setLocalBeat] = useAtom(useCreateAtom(0))const {@@ -754,10 +764,14 @@ export function LandingShellMotion({<CommunityDbProvider registry={registry}><PrototypeShellscene={scene}+ userAvatar={userAvatar}+ previewServers={previewServers}+ dms={dms}+ activeDm={activeDm}snapshot={visualSnapshot}machineIntroDescription={machineIntroDescription}overviewDetails={overviewDetails}- />+ >{children}</PrototypeShell></CommunityDbProvider></QueryClientProvider></CommunityPreviewProfileOwner>@@ -862,11 +876,21 @@ function PrototypeShell({snapshot,machineIntroDescription,overviewDetails,+ children,+ dms,+ activeDm,+ previewServers,+ userAvatar,}: {scene: LandingScenesnapshot: SceneSnapshotmachineIntroDescription?: stringoverviewDetails: boolean+ children?: ReactNode+ dms?: DM[]+ activeDm?: string+ previewServers?: Server[]+ userAvatar?: string}) {const continuityRoom = scene === "continuity" && snapshot.beat >= 7? snapshot.room@@ -882,18 +906,18 @@ function PrototypeShell({room,overviewDetails,})- const servers = overviewDetails && scene === "server"+ const servers = previewServers ?? (overviewDetails && scene === "server"? OVERVIEW_SERVERS: scene === "continuity"? SPACE_SERVERS.map((server) => ({ ...server, active: server.id === room })): room? SPACE_SERVERS.map((server) => ({ ...server, active: server.id === room }))- : SERVERS+ : SERVERS)return (<Shell className={styles.productShell}><PrototypeServerRailservers={servers}- activeServerId={room ?? "gus"}+ activeServerId={previewServers?.find(server => server.active)?.id ?? room ?? "gus"}serverView={serverView}/><div className="relative flex min-w-0 flex-1 flex-col pt-2">@@ -906,18 +930,20 @@ function PrototypeShell({{serverView ? (<PrototypeChannelSidebarroom={room}+ serverNameOverride={previewServers?.find(server => server.active)?.name}treeScopeKey={channelTreeScopeKey}channels={scene === "continuity" ? CONTINUITY_CHANNELS : SPACE_CHANNELS}rootChannels={overviewDetails && scene === "server" ? SPACE_CHANNELS.work : CHANNELS}/>) : (- <PrototypeDmSidebar scene={scene} snapshot={snapshot} />+ <PrototypeDmSidebar scene={scene} snapshot={snapshot} dms={dms} activeDm={activeDm} />)}</div><divkey={`content-${scene}-${room ?? "default"}`}className={`flex min-w-0 flex-1 flex-col bg-background ${styles.sceneEnter}`}>+ {children ?? <>{scene === "server" && (<ServerScene snapshot={snapshot} showTypingPill={overviewDetails} />)}@@ -931,11 +957,12 @@ function PrototypeShell({{scene === "spaces" && <SpacesScene snapshot={snapshot} />}{scene === "identity" && <IdentityScene snapshot={snapshot} />}{scene === "continuity" && <ContinuityScene snapshot={snapshot} />}+ </>}</div></div></AppSurface><div className="absolute bottom-0 left-0 z-10 -ml-14 w-74">- <PrototypeUserBar scene={scene} snapshot={snapshot} />+ <PrototypeUserBar scene={scene} snapshot={snapshot} userAvatar={userAvatar} /></div></div></Shell>@@ -964,9 +991,11 @@ export function landingChannelTreeScopeKey({function PrototypeUserBar({scene,snapshot,+ userAvatar,}: {scene: LandingScenesnapshot: SceneSnapshot+ userAvatar?: string}) {const rootRef = useRef<HTMLDivElement>(null)const continuityBeat = scene === "continuity" ? snapshot.beat : -1@@ -1012,7 +1041,7 @@ function PrototypeUserBar({)}<UserBarbreakpoint="desktop"- user={{ id: "gus", name: "Gus", avatar: LANDING_HUMAN_AVATARS.gus }}+ user={{ id: "gus", name: "Gus", avatar: userAvatar ?? LANDING_HUMAN_AVATARS.gus }}onEditProfile={() => {}}inbox={scene === "continuity" || scene === "server" || scene === "machine" ? <span /> : undefined}hasUnread={hasUnread}@@ -1069,19 +1098,21 @@ function PrototypeServerRail({function PrototypeChannelSidebar({room,+ serverNameOverride,treeScopeKey,channels = SPACE_CHANNELS,rootChannels = CHANNELS,}: {room: LandingRoom | null+ serverNameOverride?: stringtreeScopeKey: stringchannels?: Record<LandingRoom, Category[]>rootChannels?: Category[]}) {const categories = room ? channels[room] : rootChannels- const serverName = room+ const serverName = serverNameOverride ?? (room? SPACE_SERVERS.find((server) => server.id === room)?.name ?? ""- : "Gus"+ : "Gus")const activeChannel = categories[0]?.channels[0]?.id ?? "general"const sidebarRef = useRef<HTMLDivElement>(null)@@ -1117,7 +1148,7 @@ function PrototypeChannelSidebar({isAdmin={false}currentUserId="gus"/>- {room && (+ {(room || serverNameOverride) && (<buttondata-motion-target="invite-life"className="absolute right-2 top-2 grid size-7 place-items-center rounded-md text-muted-foreground"@@ -1133,9 +1164,13 @@ function PrototypeChannelSidebar({function PrototypeDmSidebar({scene,snapshot,+ dms = DMS,+ activeDm,}: {scene: LandingScenesnapshot: SceneSnapshot+ dms?: DM[]+ activeDm?: string}) {const sidebarRef = useRef<HTMLDivElement>(null)const dmOpen =@@ -1155,14 +1190,14 @@ function PrototypeDmSidebar({return (<div ref={sidebarRef} className="flex min-h-0 flex-1 flex-col"><DmSidebar- dms={DMS}- activeDm={dmOpen ? "dm-alli" : null}+ dms={dms}+ activeDm={activeDm ?? (dmOpen ? "dm-alli" : null)}onPickDm={() => {}}onShowFriends={() => {}}onShowMachines={() => {}}onShowBots={() => {}}machinesActive={scene === "machine"}- botsActive={scene === "provider" && !dmOpen}+ botsActive={scene === "provider" && !dmOpen && !activeDm}/></div>)@@ -1178,7 +1213,7 @@ function targetClass(snapshot: SceneSnapshot, id: string, className?: string) {.join(" ")}-function PrototypeSheet({+export function PrototypeSheet({children,label,open = true,@@ -1394,17 +1429,18 @@ function ContinuityScene({ snapshot }: { snapshot: SceneSnapshot }) {)}-function PrototypeInviteSurface({ snapshot }: { snapshot: SceneSnapshot }) {+export function PrototypeInviteSurface({ snapshot, serverName = "Home", inviteLink = "alook.ai/c/invite/home", children }: { snapshot: SceneSnapshot; serverName?: string; inviteLink?: string; children?: ReactNode }) {return (<aside- aria-label="Invite friends to Home"+ aria-label={`Invite friends to ${serverName}`}+ data-slot="dialog-content"aria-hidden={!snapshot.inviteOpen}data-open={snapshot.inviteOpen}className={styles.inviteSurface}><header className="border-b border-border/50 px-4 py-3"><div className="truncate font-heading text-sm font-semibold leading-[1.2] tracking-[-0.015em]">- Invite friends to Home+ Invite friends to {serverName}</div></header><div className="px-4 pt-3">@@ -1417,7 +1453,7 @@ function PrototypeInviteSurface({ snapshot }: { snapshot: SceneSnapshot }) {</label></div><div className="px-2 py-2">- <div className="flex items-center gap-3 rounded-md px-2 py-2">+ {children ?? <div className="flex items-center gap-3 rounded-md px-2 py-2"><Avatar label="Maya" seed="maya" size={32} presence="online" ringColor="var(--popover)" /><div className="min-w-0 flex-1"><div className="truncate text-sm font-medium">Maya</div>@@ -1438,22 +1474,22 @@ function PrototypeInviteSurface({ snapshot }: { snapshot: SceneSnapshot }) {"Invite")}</Button>- </div>+ </div>}</div><footer className="border-t border-border/50 px-4 py-3"><div className="text-xs font-medium text-muted-foreground">Or, send a server invite link to a friend</div><div className="mt-2 flex items-center gap-2">- <Input readOnly value="alook.ai/c/invite/home" className="font-mono text-xs" />- <Button size="sm">Copy</Button>+ <Input readOnly value={inviteLink} className="font-mono text-xs" />+ <Button size="sm" data-invite-copy>Copy</Button></div></footer></aside>)}-function PrototypeComposer({+export function PrototypeComposer({snapshot,target,placeholder,@@ -1761,14 +1797,16 @@ function ProviderScene({ snapshot }: { snapshot: SceneSnapshot }) {)}-function BotCard({+export function BotCard({runtime,+ name = "Alli",model,status,snapshot,menuOpen = false,}: {runtime: string+ name?: stringmodel: string | nullstatus: stringsnapshot?: SceneSnapshot@@ -1782,10 +1820,10 @@ function BotCard({<div className="relative"><Card className="flex flex-col gap-3 p-4"><div className="flex items-start gap-3">- <AgentAvatar name="Alli" seed="alli" size={40} />+ <AgentAvatar name={name} seed={name.toLowerCase()} size={40} /><div className="flex min-w-0 flex-1 flex-col gap-1"><div className="flex items-center gap-2">- <span className="text-[15px] font-medium text-foreground">Alli</span>+ <span className="text-[15px] font-medium text-foreground">{name}</span><span className="inline-flex items-center gap-1 rounded-full bg-emerald-500/10 px-2 py-1 text-[11px] font-medium text-emerald-600 dark:text-emerald-400"><span className="size-1.5 rounded-full bg-status-online" />{status}diff --git a/src/web/src/components/public-layout.dom.test.tsx b/src/web/src/components/public-layout.dom.test.tsxindex 72565c4b8..04d8951c8 100644--- a/src/web/src/components/public-layout.dom.test.tsx+++ b/src/web/src/components/public-layout.dom.test.tsx@@ -17,6 +17,8 @@ describe("PublicLayout zone navigation", () => {it("classifies only document transitions across Worker ownership", () => {expect(isCrossZoneNavigation("/guides#coding-agents", "main")).toBe(true)expect(isCrossZoneNavigation("/guides/", "blog")).toBe(false)+ expect(isCrossZoneNavigation("/tutorials", "main")).toBe(true)+ expect(isCrossZoneNavigation("/tutorials/codex-and-claude-code", "blog")).toBe(false)expect(isCrossZoneNavigation("/guides-other", "main")).toBe(true)expect(isCrossZoneNavigation("/blog", "main")).toBe(true)expect(isCrossZoneNavigation("/blogger", "main")).toBe(true)diff --git a/src/web/src/components/public-layout.tsx b/src/web/src/components/public-layout.tsxindex 03ec74327..f8f54ec76 100644--- a/src/web/src/components/public-layout.tsx+++ b/src/web/src/components/public-layout.tsx@@ -19,7 +19,7 @@ export type PublicZone = "main" | "blog";export function isCrossZoneNavigation(href: string, zone: PublicZone): boolean {if (!href.startsWith("/")) return false;- const blogOwned = href.startsWith("/blog") || href.startsWith("/og/blog") || href.startsWith("/guides");+ const blogOwned = href.startsWith("/blog") || href.startsWith("/og/blog") || href.startsWith("/guides") || href.startsWith("/tutorials");return zone === "main" ? blogOwned : !blogOwned;}@@ -50,6 +50,7 @@ export function PublicLayout({rightSlot,footer = "none",mainClassName,+ navClassName,children,}: {zone?: PublicZone;@@ -60,6 +61,7 @@ export function PublicLayout({rightSlot?: React.ReactNode;footer?: "simple" | "rich" | "none" | React.ReactElement;mainClassName?: string;+ navClassName?: string;children: React.ReactNode;}) {const maxWClass = maxWidth === "4xl" ? "max-w-4xl" : "max-w-5xl";@@ -67,7 +69,7 @@ export function PublicLayout({return (<div className="min-h-dvh flex flex-col bg-background text-foreground"><nav className="sticky top-0 z-50 bg-background/90 backdrop-blur-sm border-b border-border/40">- <div className="mx-auto flex max-w-5xl items-center justify-between px-6 py-2">+ <div className={`mx-auto flex items-center justify-between py-2 ${navClassName ?? "max-w-5xl px-6"}`}>{leftSlot ? (<div className="flex items-center gap-2">{leftSlot}</div>) : (diff --git a/src/web/src/components/ui/select.tsx b/src/web/src/components/ui/select.tsxindex d3d265bb2..3fc102361 100644--- a/src/web/src/components/ui/select.tsx+++ b/src/web/src/components/ui/select.tsx@@ -68,16 +68,17 @@ function SelectContent({align = "center",alignOffset = 0,alignItemWithTrigger = true,+ portalContainer,render,...props-}: SelectPrimitive.Popup.Props &+}: SelectPrimitive.Popup.Props & { portalContainer?: React.ComponentProps<typeof SelectPrimitive.Portal>["container"] } &Pick<SelectPrimitive.Positioner.Props,"align" | "alignOffset" | "side" | "sideOffset" | "alignItemWithTrigger">) {const renderPopup = useNativeBackPopupRender<SelectPrimitive.Popup.State>(render)return (- <SelectPrimitive.Portal>+ <SelectPrimitive.Portal container={portalContainer}><SelectPrimitive.Positionerside={side}sideOffset={sideOffset}diff --git a/src/web/src/lib/observability/coverage.ts b/src/web/src/lib/observability/coverage.tsindex b109731bb..3688cb10a 100644--- a/src/web/src/lib/observability/coverage.ts+++ b/src/web/src/lib/observability/coverage.ts@@ -27,6 +27,8 @@ export const pageRoutes = ["/templates","/templates/[id]","/terms",+ "/tutorials",+ "/tutorials/[slug]",] as constexport const apiRoutes = [diff --git a/src/web/src/lib/root-sitemap.test.ts b/src/web/src/lib/root-sitemap.test.tsindex 404c888ff..ea66a6df1 100644--- a/src/web/src/lib/root-sitemap.test.ts+++ b/src/web/src/lib/root-sitemap.test.ts@@ -1,4 +1,5 @@import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { stepGuides } from "./step-guides";import { buildRootSitemap, serializeRootSitemap } from "./root-sitemap";import type { BlogDiscoveryManifestV1 } from "./blog-discovery-manifest";@@ -39,6 +40,9 @@ describe("sitemap", () => {expect(urls).not.toContain("https://alook.ai/pricing-concept");expect(urls).toContain("https://alook.ai/blog");expect(urls).toContain("https://alook.ai/guides");+ expect(urls).toContain("https://alook.ai/tutorials");+ expect(urls.filter(url => url.startsWith("https://alook.ai/tutorials/"))).toEqual(stepGuides.map(guide => `https://alook.ai/tutorials/${guide.slug}`));+ expect(urls).not.toContain("https://alook.ai/guides/codex-and-claude-code");expect(urls).toContain("https://alook.ai/privacy");expect(urls).toContain("https://alook.ai/blog/revised");expect(urls).not.toContain("https://alook.ai/sign-in");diff --git a/src/web/src/lib/root-sitemap.ts b/src/web/src/lib/root-sitemap.tsindex 733fe41d7..ba61772da 100644--- a/src/web/src/lib/root-sitemap.ts+++ b/src/web/src/lib/root-sitemap.ts@@ -1,5 +1,6 @@import type { MetadataRoute } from "next";import type { BlogDiscoveryManifestV1 } from "@/lib/blog-discovery-manifest";+import { stepGuides } from "./step-guides";import { TEMPLATES } from "@/lib/templates";const SITE_URL = "https://alook.ai";@@ -36,6 +37,8 @@ export function buildRootSitemap(manifest: BlogDiscoveryManifestV1 | null): Meta}]: []),...(manifest ? [{ url: `${SITE_URL}/guides`, changeFrequency: "weekly" as const, priority: 0.6 }] : []),+ ...(manifest ? [{ url: `${SITE_URL}/tutorials`, changeFrequency: "weekly" as const, priority: 0.6 }] : []),+ ...(manifest ? stepGuides.map((guide) => ({ url: `${SITE_URL}/tutorials/${guide.slug}`, changeFrequency: "monthly" as const, priority: 0.6 })) : []),...blogEntries,{ url: `${SITE_URL}/contact`, changeFrequency: "monthly", priority: 0.5 },{ url: `${SITE_URL}/privacy`, changeFrequency: "yearly", priority: 0.3 },diff --git a/src/web/src/lib/seo/public-page-metadata.test.ts b/src/web/src/lib/seo/public-page-metadata.test.tsindex 81f0273c0..76314dc13 100644--- a/src/web/src/lib/seo/public-page-metadata.test.ts+++ b/src/web/src/lib/seo/public-page-metadata.test.ts@@ -13,10 +13,13 @@ import { metadata as pricing } from "@/app/pricing/page";import { metadata as blog } from "@blog/app/blog/(index)/page";import { metadata as guides } from "@blog/app/guides/page";+import { metadata as tutorials } from "@blog/app/tutorials/page";+const pages = [["home", home, "https://alook.ai", "Alook | Multi-Agent Collaboration for Team and Friends"],["pricing", pricing, "https://alook.ai/pricing", "Pricing — Free, Studio & House Plans — Alook"],["blog", blog, "https://alook.ai/blog", "Blog — AI Agent Collaboration & Workflows — Alook"],+ ["tutorials", tutorials, "https://alook.ai/tutorials", "Tutorials — Alook"],["guides", guides, "https://alook.ai/guides", "Guides — Coding Agent Collaboration — Alook"],] as const;diff --git a/src/web/src/lib/step-guides.test.ts b/src/web/src/lib/step-guides.test.tsnew file mode 100644index 000000000..b3a3ec7ba--- /dev/null+++ b/src/web/src/lib/step-guides.test.ts@@ -0,0 +1,21 @@+import { describe, expect, it } from "vitest";+import { getStepGuide, stepGuides, tutorialAgents } from "./step-guides";++describe("step guide registry", () => {+ it("registers the original and all six requested ordered pairs", () => {+ expect(stepGuides.map(guide => guide.agents)).toEqual([+ ["codex", "claude"], ["grok", "codex"], ["grok", "claude"],+ ["opencode", "codex"], ["opencode", "claude"], ["cursor", "codex"], ["cursor", "claude"],+ ]);+ for (const guide of stepGuides) {+ for (const runtime of guide.agents) expect(guide.description).toContain(tutorialAgents[runtime].name);+ }+ expect(new Set(stepGuides.map(guide => guide.connectLead)).size).toBe(7);+ expect(new Set(stepGuides.map(guide => guide.messageLead)).size).toBe(7);+ });+ it("resolves only registered routes and uses unique slugs", () => {+ expect(getStepGuide("codex-and-claude-code")?.title).toContain("Codex and Claude Code");+ expect(getStepGuide("missing")).toBeUndefined();+ expect(new Set(stepGuides.map(({ slug }) => slug)).size).toBe(stepGuides.length);+ });+});diff --git a/src/web/src/lib/step-guides.ts b/src/web/src/lib/step-guides.tsnew file mode 100644index 000000000..1966f0649--- /dev/null+++ b/src/web/src/lib/step-guides.ts@@ -0,0 +1,98 @@+export const tutorialAgents = {+ codex: { name: "Codex", setupName: "Codex", setupUrl: "https://learn.chatgpt.com/docs/cli", preparation: "Install Codex and sign in on this computer." },+ claude: { name: "Claude Code", setupName: "Claude Code", setupUrl: "https://support.claude.com/en/articles/14552382-your-first-day-in-claude-code", preparation: "Install Claude Code and sign in on this computer." },+ grok: { name: "Grok", setupName: "Grok Build", setupUrl: "https://x.ai/build", preparation: "Install Grok Build, the terminal agent, and sign in before connecting it to Alook." },+ opencode: { name: "OpenCode", setupName: "OpenCode", setupUrl: "https://opencode.ai/docs/", preparation: "Install the OpenCode CLI and configure a model provider so you can run a session locally." },+ cursor: { name: "Cursor", setupName: "Cursor CLI", setupUrl: "https://cursor.com/docs/cli/overview", preparation: "Install Cursor CLI and sign in on this computer. This walkthrough connects the terminal agent." },+} as const;++export type TutorialRuntime = keyof typeof tutorialAgents;+export type TutorialPair = readonly [TutorialRuntime, TutorialRuntime];+export const defaultTutorialPair: TutorialPair = ["codex", "claude"];++type GuideDefinition = {+ slug: string;+ agents: TutorialPair;+ description: string;+ date: string;+ connectLead: string;+ firstBotLead: string;+ secondBotLead: string;+ serverLead: string;+ messageLead: string;+};++const definitions: readonly GuideDefinition[] = [+ {+ slug: "codex-and-claude-code", agents: defaultTutorialPair, date: "2026-10-27",+ description: "Connect your computer, create Codex and Claude Code bots, and bring them into one Alook server.",+ connectLead: "Connect the computer where Codex and Claude Code are installed.",+ firstBotLead: "Start with Codex. The example names this bot Milo.",+ secondBotLead: "Add Claude Code as your second bot. The example names it Nova.",+ serverLead: "Give your Codex and Claude Code bots a shared server.",+ messageLead: "In your server’s general channel, @mention both bots and send them a task.",+ },+ {+ slug: "grok-and-codex", agents: ["grok", "codex"], date: "2026-10-28",+ description: "Create a Grok bot and a Codex bot on your computer, then invite both into an Alook server to work from the same conversation.",+ connectLead: "Use the computer where you can already run Grok Build and Codex. Connect it once for both bots.",+ firstBotLead: "Create the Grok bot first. Name it Milo, as shown below, or choose a name you will recognize in chat.",+ secondBotLead: "Next, create a separate bot for Codex on the same machine. We use Nova so the two bots are easy to tell apart.",+ serverLead: "Create a server for the work you want to share with Grok and Codex, then invite each bot.",+ messageLead: "Open general and @mention your Grok and Codex bots in one message. Give them the same task and ask them to agree on who does what.",+ },+ {+ slug: "grok-and-claude-code", agents: ["grok", "claude"], date: "2026-10-28",+ description: "Connect Grok Build and Claude Code to Alook as two bots, bring them into one server, and start a shared conversation.",+ connectLead: "Keep Grok Build and Claude Code ready on the computer you want to use. A single machine connection serves both bots.",+ firstBotLead: "Set up Grok as the first bot. The walkthrough calls it Milo; this is the name you will mention later.",+ secondBotLead: "Create Nova for Claude Code next. Keep the same machine selected and give this bot its own name.",+ serverLead: "Put both bots in a server where you can give Grok and Claude Code instructions together.",+ messageLead: "In general, mention both bots and describe what you want to work on. You can ask them to settle their roles before you give them the task.",+ },+ {+ slug: "opencode-and-codex", agents: ["opencode", "codex"], date: "2026-10-28",+ description: "Bring your configured OpenCode agent and Codex into Alook, create a bot for each, and invite them to the same server.",+ connectLead: "Connect the computer where OpenCode has a working provider configuration and Codex is signed in.",+ firstBotLead: "Make the first bot use OpenCode. We call it Milo. Choose the opencode runtime for the agent you configured locally.",+ secondBotLead: "Now give Codex its own bot on that machine. Name it Nova, or use another name distinct from your OpenCode bot.",+ serverLead: "Create a shared server for your OpenCode and Codex bots. Invite both from your own account.",+ messageLead: "Use general to give both bots the same brief. @mention OpenCode’s bot and Codex’s bot so each receives the request.",+ },+ {+ slug: "opencode-and-claude-code", agents: ["opencode", "claude"], date: "2026-10-28",+ description: "Set up OpenCode and Claude Code bots in Alook, invite them into one server, and give them a task in a shared channel.",+ connectLead: "Start with a computer where OpenCode can run with your chosen provider and Claude Code is signed in. Keep it online for both bots.",+ firstBotLead: "Create Milo for OpenCode first. Its runtime is opencode; your local OpenCode setup supplies the provider configuration.",+ secondBotLead: "Add a second bot for Claude Code, using the same connected machine. The example calls this bot Nova.",+ serverLead: "Bring the two bots into a server for your project, so you can address OpenCode and Claude Code in one place.",+ messageLead: "In general, @mention Milo and Nova and send your brief. Start by asking them to divide the work if you have not assigned roles yet.",+ },+ {+ slug: "cursor-and-codex", agents: ["cursor", "codex"], date: "2026-10-28",+ description: "Connect Cursor CLI and Codex to Alook, create two bots on your machine, and bring them into a server for shared tasks.",+ connectLead: "Choose the computer where Cursor CLI and Codex are installed and signed in. Both bots will run there.",+ firstBotLead: "Create the Cursor bot first and name it Milo. Select cursor to use the CLI you prepared on this machine.",+ secondBotLead: "Create Nova for Codex on the same machine. A separate name lets you address either bot or both in a message.",+ serverLead: "Create a server and invite your Cursor and Codex bots. Use the member list to confirm that both have joined.",+ messageLead: "Open general and @mention the Cursor and Codex bots. Send a shared request, then keep the discussion in that channel.",+ },+ {+ slug: "cursor-and-claude-code", agents: ["cursor", "claude"], date: "2026-10-28",+ description: "Create Cursor and Claude Code bots from your local CLI setup, invite them into an Alook server, and start working with both in chat.",+ connectLead: "Connect the computer that will run Cursor CLI and Claude Code. Check that both agents work there before you create their bots.",+ firstBotLead: "Start by creating a bot for Cursor CLI. The example uses Milo as its name and cursor as its runtime.",+ secondBotLead: "Add Claude Code as Nova, your second bot. Select the same online machine and the claude runtime.",+ serverLead: "Give Cursor and Claude Code a shared server, then invite the two bots you just created.",+ messageLead: "In general, mention both bots and explain the task. You can first ask them to agree on their roles, as the animation shows.",+ },+];++export const stepGuides = definitions.map((guide) => ({+ ...guide,+ title: `Use ${tutorialAgents[guide.agents[0]].name} and ${tutorialAgents[guide.agents[1]].name} together in Alook`,+}));++export function getStepGuide(slug: string) {+ return stepGuides.find((guide) => guide.slug === slug);+}diff --git a/src/web/src/test/e2e-ui/19-marketing-seo.spec.ts b/src/web/src/test/e2e-ui/19-marketing-seo.spec.tsindex f00a4196e..8d23efe2b 100644--- a/src/web/src/test/e2e-ui/19-marketing-seo.spec.ts+++ b/src/web/src/test/e2e-ui/19-marketing-seo.spec.ts@@ -100,7 +100,7 @@ test("homepage header, body, and footer share responsive content edges", async (}})-test("homepage shares header and footer site links and collapses mobile header links", async ({ page }) => {+test("homepage keeps Tutorials in the footer and collapses mobile header links", async ({ page }) => {await page.setViewportSize({ width: 390, height: 844 })await page.goto("/")await page.evaluate(() => window.scrollTo(0, document.documentElement.scrollHeight))@@ -127,7 +127,10 @@ test("homepage shares header and footer site links and collapses mobile header l}))expect(await mobileLinks.evaluateAll(linkContract)).toEqual(expectedLinks)const footerLinks = page.getByTestId(tid.landingFooterNavigation).locator("a")- expect(await footerLinks.evaluateAll(linkContract)).toEqual(expectedLinks)+ expect(await footerLinks.evaluateAll(linkContract)).toEqual([+ ...expectedLinks,+ { href: "/tutorials", label: "Tutorials" },+ ])const styleContract = (element: Element) => {const style = getComputedStyle(element)