create-smoodly-app 0.0.45 → 0.0.47

package/README.md

@@ -2,18 +2,23 @@
 
     npx create-smoodly-app my-site
 
-A fresh Next.js app with the Smoodly admin mounted at `/admin`, a Supabase
-project holding the schema, `.env.local` written, and a first editor who can
-sign in.
+A fresh Astro or Next.js site with the Smoodly admin mounted at `/admin`, a
+Supabase project holding the schema, `.env` (Astro) or `.env.local` (Next)
+written, and a first editor who can sign in.
 
 ## What it asks
 
 1. Project name (also the positional argument).
-2. **Multilingual?** No (default) scaffolds one language. Yes asks for the
-   locales, comma-separated, the first being the default (`en, fi`), and
-   scaffolds the next-intl layout: the site under `app/[locale]/`, `i18n/`,
-   `proxy.ts`, translated URLs per locale. Flag: `--locales en,fi`.
-3. Where content lives: a **local Supabase stack** (`supabase init` +
+2. **Framework**: Astro (the default, and what `--yes` takes) or Next.js.
+   Flag: `--framework astro|next`. The questions below apply to both; the
+   Astro site ships no React, and writes `.env` (its `npm start` reads it)
+   with `SITE_URL` on port 4321.
+3. **Multilingual?** No (default) scaffolds one language. Yes asks for the
+   locales, comma-separated, the first being the default (`en, fi`). Next
+   gets the next-intl layout: the site under `app/[locale]/`, `i18n/`,
+   `proxy.ts`, translated URLs per locale; Astro gets its own i18n config
+   (`astro.config.ts` and `src/smoodly/config.ts`). Flag: `--locales en,fi`.
+4. Where content lives: a **local Supabase stack** (`supabase init` +
    `supabase start` inside the app, with the services Smoodly never uses
    excluded — the image proxy, edge functions, analytics, the pooler —
    so the stack stays small beside any other you run; needs
@@ -29,14 +34,14 @@ sign in.
    project is Smoodly's own: its tables are created unprefixed in `public`,
    so an app that keeps its own tables in Supabase gives them a project of
    their own, or takes Smoodly Cloud for content (DESIGN.md §1).
-4. The first editor: pick an existing Auth user or create one (email +
+5. The first editor: pick an existing Auth user or create one (email +
    password). The `members` row is written with role `admin`, the email
    beside the id.
    If `@` does not appear when you type it (macOS, `@` on Option+2 with the
    terminal's "Option as Meta" setting on), paste the address or pass
    `--editor-email`.
 
-Every prompt has a flag, so CI can run it: `--supabase local|hosted`, `--locales`,
+Every prompt has a flag, so CI can run it: `--framework astro|next`, `--supabase local|hosted`, `--locales`,
 `--url`, `--publishable-key`, `--secret-key`, `--editor-email` (password from
 `SMOODLY_EDITOR_PASSWORD`), `--skip-link`, `--yes`. `--help` lists them.
 A hidden `--smoodly-dep <spec>` overrides the `smoodly` dependency written into

package/dist/index.js

@@ -32,6 +32,7 @@ function parseFlags(argv) {
       "smoodly-dep": { type: "string" },
       locales: { type: "string" },
       starter: { type: "string" },
+      framework: { type: "string" },
       "skip-link": { type: "boolean", default: false },
       yes: { type: "boolean", short: "y", default: false },
       help: { type: "boolean", short: "h", default: false }
@@ -46,6 +47,10 @@ function parseFlags(argv) {
   if (starter !== void 0 && starter !== "lorem" && starter !== "blank") {
     throw new Error(`--starter must be "lorem" or "blank", got "${starter}"`);
   }
+  const framework = values.framework;
+  if (framework !== void 0 && framework !== "astro" && framework !== "next") {
+    throw new Error(`--framework must be "astro" or "next", got "${framework}"`);
+  }
   return {
     name: positionals[0],
     supabase,
@@ -58,10 +63,11 @@ function parseFlags(argv) {
     help: values.help ?? false,
     smoodlyDep: values["smoodly-dep"],
     locales: values.locales === void 0 ? void 0 : parseLocales(values.locales),
-    starter
+    starter,
+    framework
   };
 }
-var HELP = `create-smoodly-app \u2014 a fresh Next.js site with Smoodly installed
+var HELP = `create-smoodly-app \u2014 a fresh Astro or Next.js site with Smoodly installed
 
 Usage: npx create-smoodly-app [folder] [options]
 
@@ -69,8 +75,9 @@ Usage: npx create-smoodly-app [folder] [options]
   the package name: lowercase letters, digits, dots, dashes and underscores.
 
 Options:
+  --framework astro|next    The framework (asked when omitted; astro is the default)
   --supabase local|hosted   Where content lives (asked when omitted; local needs the Supabase CLI)
-  --locales <a,b,\u2026>         Multilingual: the locales, first is the default (scaffolds next-intl; omitted = one language)
+  --locales <a,b,\u2026>         Multilingual: the locales, first is the default (Astro i18n or next-intl; omitted = one language)
   --starter lorem|blank     lorem: the Lorem Co. tour of every feature (default); blank: one of each, for building your own
   --url <url>               Hosted: the Supabase project URL
   --publishable-key <key>   Hosted: the anon / publishable key
@@ -145,15 +152,15 @@ async function hasCommand(cmd, run2, cwd) {
 
 // src/ports-net.ts
 import { createServer } from "node:net";
-function canListen(port, host) {
+function canListen(port2, host) {
   return new Promise((resolve3) => {
     const server = createServer();
     server.once("error", () => resolve3(false));
-    server.listen(port, host, () => server.close(() => resolve3(true)));
+    server.listen(port2, host, () => server.close(() => resolve3(true)));
   });
 }
-async function isPortFree(port) {
-  return await canListen(port, "127.0.0.1") && await canListen(port, "0.0.0.0");
+async function isPortFree(port2) {
+  return await canListen(port2, "127.0.0.1") && await canListen(port2, "0.0.0.0");
 }
 
 // src/prompts.ts
@@ -161,7 +168,7 @@ import * as p from "@clack/prompts";
 import { resolve as resolve2 } from "node:path";
 
 // src/env.ts
-function renderEnv(keys) {
+function renderEnv(keys, siteUrl2 = "http://localhost:3000") {
   return [
     "# Smoodly, self-host: the content project's values. The live site reads",
     "# with SMOODLY_URL and SMOODLY_SECRET_KEY; the admin also signs in with",
@@ -173,7 +180,7 @@ function renderEnv(keys) {
     "",
     "# The site's own address: absolute hreflang and social URLs. Set it to",
     "# the production URL where you deploy.",
-    "SITE_URL=http://localhost:3000",
+    `SITE_URL=${siteUrl2}`,
     ""
   ].join("\n");
 }
@@ -224,6 +231,8 @@ async function isEmptyOrMissing(dir) {
 }
 var ROUTING_LOCALES = '  locales: ["en", "fi"],';
 var ROUTING_DEFAULT = '  defaultLocale: "en",';
+var ASTRO_I18N_LINE = '  i18n: { locales: ["en", "fi"], defaultLocale: "en" },';
+var ASTRO_CONFIG_LOCALES_LINE = '  locales: { default: "en", supported: ["en", "fi"] },';
 var ARTICLES_PATH_LINE = '  path: { en: "posts", fi: "artikkelit" },';
 var ARTICLES_SLUG_LINE = '  slug: { en: "posts", fi: "artikkelit" },';
 var NEWS_PATH_LINE = '  path: { en: "company/news", fi: "yritys/uutiset" },';
@@ -244,7 +253,20 @@ async function scaffold(opts) {
   pkg.name = opts.name;
   if (opts.smoodlyDep) pkg.dependencies.smoodly = opts.smoodlyDep;
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-  if (opts.locales) {
+  const astro = opts.framework === "astro";
+  const root = astro ? "src/" : "";
+  if (opts.locales && astro) {
+    const rewriteLine = async (rel, line, next) => {
+      const path = join(opts.dir, rel);
+      const source = await readFile(path, "utf8");
+      if (!source.includes(line)) throw new Error(`${rel} in the template has drifted; expected the line
+${line}`);
+      await writeFile(path, source.replace(line, next));
+    };
+    await rewriteLine("astro.config.ts", ASTRO_I18N_LINE, `  i18n: { locales: [${opts.locales.map((l) => JSON.stringify(l)).join(", ")}], defaultLocale: ${JSON.stringify(opts.locales[0])} },`);
+    await rewriteLine("src/smoodly/config.ts", ASTRO_CONFIG_LOCALES_LINE, `  locales: { default: ${JSON.stringify(opts.locales[0])}, supported: [${opts.locales.map((l) => JSON.stringify(l)).join(", ")}] },`);
+  }
+  if (opts.locales && !astro) {
     const routingPath = join(opts.dir, "i18n/routing.ts");
     const routing = await readFile(routingPath, "utf8");
     if (!routing.includes(ROUTING_LOCALES) || !routing.includes(ROUTING_DEFAULT)) {
@@ -254,23 +276,25 @@ async function scaffold(opts) {
       routingPath,
       routing.replace(ROUTING_LOCALES, `  locales: [${opts.locales.map((l) => JSON.stringify(l)).join(", ")}],`).replace(ROUTING_DEFAULT, `  defaultLocale: ${JSON.stringify(opts.locales[0])},`)
     );
-    const source = await readFile(join(opts.dir, "messages", "en.json"), "utf8").catch(() => null);
+  }
+  if (opts.locales) {
+    const source = await readFile(join(opts.dir, `${root}messages`, "en.json"), "utf8").catch(() => null);
     if (source !== null) {
       for (const locale of opts.locales) {
-        const file = join(opts.dir, "messages", `${locale}.json`);
+        const file = join(opts.dir, `${root}messages`, `${locale}.json`);
         if (await readFile(file, "utf8").catch(() => null) === null) await writeFile(file, source);
       }
     }
     if (opts.starter !== "blank") {
       const rewrites = [
-        { map: articlesSegments(opts.locales), from: '{ en: "posts", fi: "artikkelit" }', lines: [["smoodly/collections.ts", ARTICLES_PATH_LINE], ["components/pages/Articles.tsx", ARTICLES_SLUG_LINE]] },
-        { map: newsSegments(opts.locales), from: '{ en: "company/news", fi: "yritys/uutiset" }', lines: [["smoodly/collections.ts", NEWS_PATH_LINE], ["components/pages/News.tsx", NEWS_SLUG_LINE]] }
+        { map: articlesSegments(opts.locales), from: '{ en: "posts", fi: "artikkelit" }', lines: [["smoodly/collections.ts", ARTICLES_PATH_LINE], ["components/pages/Articles.schema.ts", ARTICLES_SLUG_LINE]] },
+        { map: newsSegments(opts.locales), from: '{ en: "company/news", fi: "yritys/uutiset" }', lines: [["smoodly/collections.ts", NEWS_PATH_LINE], ["components/pages/News.schema.ts", NEWS_SLUG_LINE]] }
       ];
       for (const { map, from, lines } of rewrites) {
         for (const [rel, line] of lines) {
-          const path = join(opts.dir, rel);
+          const path = join(opts.dir, root + rel);
           const source2 = await readFile(path, "utf8");
-          if (!source2.includes(line)) throw new Error(`${rel} in the template has drifted; expected the line
+          if (!source2.includes(line)) throw new Error(`${root}${rel} in the template has drifted; expected the line
 ${line}`);
           await writeFile(path, source2.replace(line, line.replace(from, map)));
         }
@@ -302,7 +326,16 @@ async function resolveAnswers(flags2, ctx, env = process.env) {
   const invalid = validName(name);
   if (invalid) bail(invalid);
   if (!await isEmptyOrMissing(dir)) bail(`${dir} exists and is not empty.`);
-  const locales = flags2.locales ?? (flags2.yes ? void 0 : await answer(p.confirm({ message: "Multilingual site? (next-intl, translated URLs)", initialValue: false })) ? await answer(
+  const framework = flags2.framework ?? (flags2.yes ? "astro" : await answer(
+    p.select({
+      message: "Framework?",
+      options: [
+        { value: "astro", label: "Astro", hint: "sections as .astro files, pages cached whole and expired by tag" },
+        { value: "next", label: "Next.js", hint: "sections as React server components" }
+      ]
+    })
+  ));
+  const locales = flags2.locales ?? (flags2.yes ? void 0 : await answer(p.confirm({ message: `Multilingual site? (${framework === "astro" ? "Astro i18n" : "next-intl"}, translated URLs)`, initialValue: false })) ? await answer(
     p.text({
       message: "Locales, comma-separated, the first is the default",
       placeholder: "en, fr",
@@ -336,7 +369,7 @@ async function resolveAnswers(flags2, ctx, env = process.env) {
   if (supabase === "local") {
     if (!ctx.hasSupabaseCli) bail("Local mode needs the Supabase CLI: https://supabase.com/docs/guides/cli (brew install supabase/tap/supabase)");
     if (flags2.editorEmail && !env.SMOODLY_EDITOR_PASSWORD) throw new Error(`Set SMOODLY_EDITOR_PASSWORD to create ${flags2.editorEmail}.`);
-    return { name, dir, supabase, hasSupabaseCli: true, smoodlyDep: flags2.smoodlyDep, locales, starter };
+    return { name, dir, supabase, hasSupabaseCli: true, smoodlyDep: flags2.smoodlyDep, locales, starter, framework };
   }
   const badUrl = "Supabase project URL must be an http(s) URL, like https://abcd.supabase.co";
   const typedUrl = flags2.url ?? await answer(
@@ -355,7 +388,7 @@ async function resolveAnswers(flags2, ctx, env = process.env) {
     p.log.warn(`No project ref in ${url}; skipping supabase link. Run \`supabase link --project-ref <project-ref>\` and \`supabase db push\` yourself.`);
   }
   const linkAndPush = !ctx.hasSupabaseCli ? false : flags2.skipLink || !ref ? false : flags2.yes ? true : await answer(p.confirm({ message: `Link this app to the project and push the migration now? (supabase link --project-ref ${ref}, supabase db push)` }));
-  return { name, dir, supabase, hasSupabaseCli: ctx.hasSupabaseCli, hosted: { keys: { url, publishableKey, secretKey }, linkAndPush }, smoodlyDep: flags2.smoodlyDep, locales, starter };
+  return { name, dir, supabase, hasSupabaseCli: ctx.hasSupabaseCli, hosted: { keys: { url, publishableKey, secretKey }, linkAndPush }, smoodlyDep: flags2.smoodlyDep, locales, starter, framework };
 }
 function askEditorWith(flags2, env = process.env) {
   return async (existing) => {
@@ -388,8 +421,9 @@ function askEditorWith(flags2, env = process.env) {
 import { join as join2 } from "node:path";
 
 // src/plan.ts
-function templateName(starter, locales) {
-  return locales === "intl" ? `${starter}-intl` : starter;
+function templateName(framework, starter, locales) {
+  const base = locales === "intl" ? `${starter}-intl` : starter;
+  return framework === "astro" ? `astro-${base}` : base;
 }
 function plan(a) {
   if (a.supabase === "local" && !a.hasSupabaseCli) {
@@ -420,8 +454,8 @@ async function findFreeBlock(ports, isFree, bases = BASES) {
   for (const base of bases) {
     const shifted = ports.map((p3) => base + (p3 - DEFAULT_BASE));
     let allFree = true;
-    for (const port of shifted) {
-      if (!await isFree(port)) {
+    for (const port2 of shifted) {
+      if (!await isFree(port2)) {
         allFree = false;
         break;
       }
@@ -465,12 +499,13 @@ async function run(answers2, deps) {
       switch (step) {
         case "copyTemplate":
           await deps.fs.scaffold({
-            templateDir: deps.templateDirs[templateName(answers2.starter ?? "lorem", answers2.locales ? "intl" : "single")],
+            templateDir: deps.templateDirs[templateName(answers2.framework, answers2.starter ?? "lorem", answers2.locales ? "intl" : "single")],
             dir: cwd,
             name: answers2.name,
             smoodlyDep: answers2.smoodlyDep,
             locales: answers2.locales,
-            starter: answers2.starter
+            starter: answers2.starter,
+            framework: answers2.framework
           });
           break;
         case "install":
@@ -478,7 +513,7 @@ async function run(answers2, deps) {
           await sh("npm", ["install"]);
           break;
         case "gitInit":
-          await deps.agentFiles?.(cwd).catch(() => {
+          if (answers2.framework === "next") await deps.agentFiles?.(cwd).catch(() => {
           });
           await sh("git", ["init"], { capture: true });
           await sh("git", ["add", "-A"], { capture: true });
@@ -520,7 +555,7 @@ async function run(answers2, deps) {
           await sh("supabase", ["db", "push"]);
           break;
         case "writeEnv":
-          await deps.fs.writeFile(join2(cwd, ".env.local"), renderEnv(ctx.keys));
+          await deps.fs.writeFile(join2(cwd, envFile(answers2)), renderEnv(ctx.keys, siteUrl(answers2)));
           break;
         case "ensureEditor":
           ctx.editor = await ensureEditor(deps.editorClient(ctx.keys), deps.askEditor);
@@ -548,10 +583,12 @@ async function run(answers2, deps) {
   return { ok: true, keys: ctx.keys, editor: ctx.editor };
 }
 var withoutSeedSql = (toml) => toml.replace(/(\[db\.seed\]\n(?:#.*\n)*enabled = )true/, "$1false");
+var envFile = (answers2) => answers2.framework === "astro" ? ".env" : ".env.local";
+var siteUrl = (answers2) => answers2.framework === "astro" ? "http://localhost:4321" : "http://localhost:3000";
 function fallbackFor(step, answers2, keys) {
-  const envLines = keys ? `Write ${answers2.dir}/.env.local:
+  const envLines = keys ? `Write ${answers2.dir}/${envFile(answers2)}:
 
-${renderEnv(keys).split("\n").filter((l) => !l.startsWith("#")).join("\n").trimEnd()}` : `Write ${answers2.dir}/.env.local with SMOODLY_URL, SMOODLY_SECRET_KEY and SMOODLY_PUBLISHABLE_KEY (from \`supabase status\`), and SITE_URL=http://localhost:3000.`;
+${renderEnv(keys, siteUrl(answers2)).split("\n").filter((l) => !l.startsWith("#")).join("\n").trimEnd()}` : `Write ${answers2.dir}/${envFile(answers2)} with SMOODLY_URL, SMOODLY_SECRET_KEY and SMOODLY_PUBLISHABLE_KEY (from \`supabase status\`), and SITE_URL=${siteUrl(answers2)}.`;
   const editorLines = [
     "Create the first editor, then the starter content:",
     "",
@@ -597,7 +634,11 @@ var TEMPLATE_DIRS = {
   lorem: fileURLToPath(new URL("../templates/lorem/", import.meta.url)),
   "lorem-intl": fileURLToPath(new URL("../templates/lorem-intl/", import.meta.url)),
   blank: fileURLToPath(new URL("../templates/blank/", import.meta.url)),
-  "blank-intl": fileURLToPath(new URL("../templates/blank-intl/", import.meta.url))
+  "blank-intl": fileURLToPath(new URL("../templates/blank-intl/", import.meta.url)),
+  "astro-lorem": fileURLToPath(new URL("../templates/astro-lorem/", import.meta.url)),
+  "astro-lorem-intl": fileURLToPath(new URL("../templates/astro-lorem-intl/", import.meta.url)),
+  "astro-blank": fileURLToPath(new URL("../templates/astro-blank/", import.meta.url)),
+  "astro-blank-intl": fileURLToPath(new URL("../templates/astro-blank-intl/", import.meta.url))
 };
 var flags;
 try {
@@ -649,15 +690,16 @@ if (!outcome.ok) {
   if (outcome.fallback) p2.note(outcome.fallback, "Finish by hand");
   process.exit(1);
 }
+var port = answers.framework === "astro" ? 4321 : 3e3;
 p2.note(
   [
     ...relative(process.cwd(), answers.dir) ? [`cd ${relative(process.cwd(), answers.dir)}`] : [],
     "npm run dev",
     "",
-    answers.starter === "blank" ? "Site:  http://localhost:3000  (a blank site \u2014 build it in components/ and at /admin)" : "Site:  http://localhost:3000  (the Lorem Co. starter \u2014 edit it at /admin)",
-    "Admin: http://localhost:3000/admin",
+    answers.starter === "blank" ? `Site:  http://localhost:${port}  (a blank site \u2014 build it in ${answers.framework === "astro" ? "src/sections/, src/components/" : "components/"} and at /admin)` : `Site:  http://localhost:${port}  (the Lorem Co. starter \u2014 edit it at /admin)`,
+    `Admin: http://localhost:${port}/admin`,
     `Editor: ${outcome.editor.email ?? outcome.editor.id}`,
-    ...answers.locales ? [`Locales: ${answers.locales.join(", ")} (i18n/routing.ts)`] : []
+    ...answers.locales ? [`Locales: ${answers.locales.join(", ")} (${answers.framework === "astro" ? "astro.config.ts and src/smoodly/config.ts" : "i18n/routing.ts"})`] : []
   ].join("\n"),
   "Ready"
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-smoodly-app",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "description": "Create a Smoodly site: a fresh Next.js app with the admin mounted, a Supabase schema, an env file and a first editor.",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc --noEmit && npm run typecheck:templates",
-    "typecheck:templates": "npm run build:template && tsc -p templates/lorem.tsconfig.json && tsc -p templates/lorem-intl.tsconfig.json && tsc -p templates/blank.tsconfig.json && tsc -p templates/blank-intl.tsconfig.json"
+    "typecheck:templates": "npm run build:template && tsc -p templates/lorem.tsconfig.json && tsc -p templates/lorem-intl.tsconfig.json && tsc -p templates/blank.tsconfig.json && tsc -p templates/blank-intl.tsconfig.json && tsc -p templates/astro-lorem.tsconfig.json && tsc -p templates/astro-lorem-intl.tsconfig.json && tsc -p templates/astro-blank.tsconfig.json && tsc -p templates/astro-blank-intl.tsconfig.json"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",

package/templates/astro-blank/AGENTS.md

@@ -0,0 +1,55 @@
+# Working in this Smoodly site
+
+This is an Astro site with Smoodly installed: content lives in Supabase, the admin is mounted at /admin by the `smoodly/astro` integration in `astro.config.ts`, and the site reads content through live collections (`src/live.config.ts`). Read README.md first: it says where things are.
+
+## Rules
+
+- **Register schemas in the config; views are files by name.** A section's view is
+  `src/sections/<name>.astro`, an element's `src/elements/<name>.astro`, a page
+  type's `src/page-types/<name>.astro`, an entry page's
+  `src/entry-pages/<collection>.astro`, where <name> is the schema's `name`.
+  The schema is listed in its barrel (`src/smoodly/sections.ts`, `elements.ts`,
+  the config's `pages`; collections and global items in `collections.ts`,
+  `globals.ts`) and `src/smoodly/config.ts` is the one registry. The server
+  names a schema with no file, and a file with no schema, at the first request.
+- **A `.schema.ts` file imports no component.** Zones, toolsets, global items and
+  `node()` take schemas (`z.locked(heroSchema)`), never views.
+- **After a new collection or a `smoodly` upgrade, run `npx smoodly migrate`**
+  and apply what it writes (`supabase db push` hosted, `supabase migration up`
+  local). It copies the core schema files the package ships and writes a
+  read view and order index per collection. Never edit a file it wrote.
+  The admin reads the base tables, so it lists a collection either way;
+  the view is for SQL and PostgREST readers, the index for `order`.
+- **Content from code goes through `createContent(config)`** from `smoodly/astro`:
+  `scripts/seed.ts` is starter content written with it — the admin's own
+  operations, so validation and publish checks apply and a failure throws. Never
+  write rows or call the stores directly. The seed is idempotent; `npm run seed`.
+- **Reads are live collections.** `src/live.config.ts` names one loader per
+  collection, global item, the pages and the page tree; a view reads with
+  `getLiveCollection("articles", { locale })` or `getLiveEntry("footer", { locale })`
+  from `astro:content`. Every read tags the response, and a publish expires it.
+- **The admin, the preview address and the page shell are injected** by
+  `smoodly()` in `astro.config.ts`; the project has no route file for them. A page
+  file of your own under `src/pages` wins its address. `site` in `astro.config.ts`
+  is the site's own address (from `SITE_URL`).
+- **A link an editor typed goes through `safeHref`** from "smoodly" in an `.astro`
+  view: `<a href={safeHref(link.href)}>`. Astro writes attributes as given, so a
+  `javascript:` URL would reach the page; the template build refuses a shipped
+  view that skips it.
+- **Section styles are inline.** `<Section>` from `smoodly/astro/components` renders
+  the root element with Smoodly's styles set and the node id; marks
+  (`smoodly.marks(schema)`) tie rendered elements to fields.
+- **Multilingual sites.** The locale set is `locales` in `src/smoodly/config.ts`
+  and `i18n` in `astro.config.ts`; the two must agree. UI strings of the site's
+  own go through `src/strings.ts` and `src/messages/<locale>.json`.
+- **Fixed versus open pages.** A page type with a `slug` is fixed: one
+  record, created for you, never deleted. Without one it is open: editors
+  create as many as they like.
+
+## Commands
+
+    npm run dev          # http://localhost:4321, /admin is the editor
+    npm run build        # checks the schema files (smoodly migrate --check), then astro build
+    npm run start        # the built server (dist/server/entry.mjs)
+    npm run seed         # starter content, idempotent
+    npm run typecheck    # astro check

package/templates/astro-blank/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/astro-blank/README.md

@@ -0,0 +1,88 @@
+# Smoodly site
+
+Created by `create-smoodly-app`. Content lives in Supabase; the admin is
+mounted at `/admin` by the `smoodly/astro` integration. AGENTS.md holds the
+rules for an agent (or a person) building the site.
+
+    npm run dev          # http://localhost:4321 — /admin is the editor
+
+## Where things are
+
+- `astro.config.ts` — the `smoodly()` integration (it mounts the admin, the preview address and the page shell), the node adapter, the cache and `site` (from `SITE_URL`).
+- `src/page-types/` — one view per page type: `home.astro` (fixed at /, one freeform zone) and `page.astro` (open, editors create many).
+- `src/entry-pages/posts.astro` — the entry page of the posts collection, at /posts/<slug>.
+- `src/sections/text.astro` and `src/components/sections/Text.schema.ts` — the one section: a title and a richtext body.
+- `src/elements/button.astro` and `src/components/elements/Button.schema.ts` — the one element: a link styled as a button, embedded in richtext through `src/smoodly/toolsets.ts`.
+- `src/components/LocaleNav.astro` — the language links every page view renders from its `locales` map; nothing with one locale.
+- `src/layouts/Layout.astro` — the document every view renders: the head, the footer line from the `site` global item, `src/styles/global.css`.
+- `src/smoodly/` — the wiring: `config.ts` (the registry of schemas and the settings), `collections.ts` (posts), `globals.ts` (the site item), `sections.ts` and `elements.ts` (the schemas the config registers), `toolsets.ts`.
+- `src/live.config.ts` — the live collections the views read with `getLiveCollection` and `getLiveEntry`.
+- `scripts/seed.ts` — the home page and the site item, written through `createContent(config)`. `npm run seed` is idempotent.
+- `src/styles/global.css` — a reset, a container, the two tones. Replace it.
+- `.env` — `SMOODLY_URL`, `SMOODLY_SECRET_KEY`, `SMOODLY_PUBLISHABLE_KEY`.
+
+## Add a section
+
+Copy `src/components/sections/Text.schema.ts`, give the schema a new
+`name` and `title` and declare its fields. List it in `sections` in
+`src/smoodly/sections.ts` and in the `sections` of every zone that may
+hold it in `src/components/pages/*.schema.ts`. Then write its view,
+`src/sections/<name>.astro`, by copying `text.astro`: render the fields
+inside `<Section>` with marks on each. It appears in the editor's "+"
+picker. A schema with no view, and a view with no schema, are named at
+the first request.
+
+## Add an element
+
+Copy `src/components/elements/Button.schema.ts` (relative imports only).
+Add the schema to `elements` in `src/smoodly/elements.ts` and to the
+`elements` of the toolset in `src/smoodly/toolsets.ts` that may embed
+it, and write `src/elements/<name>.astro`. A link an editor types goes
+through `safeHref`, as in `button.astro`. It appears in the richtext
+editor's "/" menu.
+
+## Add a collection
+
+Copy the `posts` block in `src/smoodly/collections.ts`, add the new
+collection to `collections` and a loader for it in `src/live.config.ts`,
+and write its entry page, `src/entry-pages/<collection>.astro`, by
+copying `posts.astro`. Then write its read view and order index and
+apply them:
+
+    npx smoodly migrate
+    supabase db push        # hosted; `supabase migration up` for the local stack (keeps the content)
+
+The same command brings the core schema forward after a `smoodly` upgrade.
+
+## Add a global item
+
+Copy the `site` block in `src/smoodly/globals.ts`, add it to `globals`
+and give it a loader in `src/live.config.ts`. A view reads it with
+`getLiveEntry("name", { locale })`. Edit it under Globals in the admin.
+
+Reseed an empty database any time with `npm run seed`.
+
+## Moving the admin
+
+The admin is at `/admin`. To serve it somewhere else, say `/studio`:
+
+1. set `smoodly({ adminPath: "/studio" })` in `astro.config.ts`,
+2. set `admin: { path: "/studio" }` in `src/smoodly/config.ts`.
+
+The two must agree; the admin says so when they do not.
+
+## Editors
+
+Anyone who may open `/admin` is a Supabase Auth user with a row in the
+`editors` table. To add one: create the user in Supabase Studio
+(Authentication → Users), then in the SQL editor:
+
+    insert into editors (user_id, role) values ('<the user id>', 'editor');
+
+## Hosted Supabase
+
+    supabase init        # if the CLI has not been set up here yet
+    supabase link        # pick the project
+    supabase db push     # applies supabase/migrations/
+
+Then put the project's URL and keys in `.env`.

package/templates/astro-blank/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.astro/
+.env
+smoodly-export-*

package/templates/astro-blank/astro.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig, memoryCache } from "astro/config";
+import node from "@astrojs/node";
+import smoodly from "smoodly/astro";
+
+export default defineConfig({
+  output: "server",
+  adapter: node({ mode: "standalone" }),
+  // Pages are cached whole and expire by tag when an editor publishes (one process, one cache).
+  cache: { provider: memoryCache() },
+  // The site's own address: canonical, hreflang and social links are absolute on it. Astro reads astro.config
+  // before .env, so this sees only a SITE_URL set in the shell; when it is unset, smoodly() sets `site` from
+  // SITE_URL in .env. Set SITE_URL where you deploy: `site` is fixed at `astro build`.
+  site: process.env.SITE_URL,
+  integrations: [smoodly({ config: "src/smoodly/config.ts" })],
+});

package/templates/astro-blank/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "smoodly-site",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "smoodly migrate --check && astro build",
+    "start": "node --env-file-if-exists=.env dist/server/entry.mjs",
+    "seed": "tsx scripts/seed.ts",
+    "typecheck": "astro check"
+  },
+  "dependencies": {
+    "@astrojs/node": "^11.1.6",
+    "@supabase/supabase-js": "^2.113.0",
+    "astro": "^7.3.5",
+    "smoodly": "0.0.47"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@types/node": "^26.4.1",
+    "typescript": "^5",
+    "tsx": "^4"
+  }
+}

package/templates/astro-blank/scripts/seed.ts

@@ -0,0 +1,80 @@
+// The starter's content, written through the content API (`createContent(config)`
+// from smoodly/astro): the admin's own operations, so validation and
+// the publish checks apply and a failure throws. It is also the example
+// of writing content from code. Ships in the scaffold; create-smoodly-app
+// runs `npm run seed` after the first editor. Idempotent: exits once the
+// home page has content in the default locale. Writes the same copy into every configured locale, whatever
+// their codes, so every locale's "/" resolves.
+// Run: npm run seed  (needs .env and a Supabase stack).
+import type { PageTree, TreeNode } from "smoodly";
+
+const { config } = await import("../src/smoodly/config");
+const { node } = await import("smoodly");
+const { createContent } = await import("smoodly/astro");
+const { content } = createContent(config);
+const { textSchema } = await import("../src/components/sections/Text.schema");
+const c = content;
+
+const DEFAULT = config.locales.default;
+const OTHERS = config.locales.supported.filter((l) => l !== DEFAULT);
+
+// The home page is code-owned: `find` returns its record, creating it when
+// the database is new. It is seeded once somebody has given it sections.
+const home = (await c.pages.find(DEFAULT, "/"))!;
+if (Object.values((await c.pages.getTree(home.id, DEFAULT))?.zones ?? {}).some((nodes) => nodes.length > 0)) {
+  console.log(`Already seeded — the home page has content in "${DEFAULT}".`);
+  process.exit(0);
+}
+
+// Richtext is TipTap JSON, the stored format; RichText renders it.
+type Node = Record<string, unknown>;
+const p = (s: string): Node => ({ type: "paragraph", content: [{ type: "text", text: s }] });
+const button = (label: string, href: string): Node => ({ type: "element", attrs: { name: "button", fields: { label, href }, settings: {} } });
+const doc = (...content: Node[]) => ({ type: "doc", content });
+
+// --- the site item: name and tagline, published in every locale ------
+
+for (const locale of [DEFAULT, ...OTHERS]) {
+  await c.globals.set("site", locale, { name: "My site", tagline: "Built with Smoodly" });
+  await c.globals.publish("site", locale);
+}
+
+// --- the home page: one Text section and one custom section ----------
+
+// The custom section is not a registered section, so it is a plain node object.
+const custom: TreeNode = {
+  id: "node-custom",
+  type: "custom",
+  fields: { rows: [
+    { spans: [6, 6], gap: "md", align: "top", reverse: false, columns: [
+      doc(p("A custom section holds rows of columns. Drag the width bar in the inspector to resize them.")),
+      doc(p("Each column is richtext. Columns stack on small screens; the developer's stylesheet needs nothing.")),
+    ] },
+  ] },
+};
+
+const tree: PageTree = {
+  meta: { description: "A new site, built with Smoodly." },
+  zones: {
+    body: [
+      node(textSchema, {
+        title: "Hello",
+        body: doc(
+          p("This is your home page. Open the admin to edit this text, add sections, create pages and write posts."),
+          p("Everything you see is defined in components/ and registered in smoodly/. The README says where things are."),
+          button("Open the admin", "/admin"),
+        ),
+      }, { id: "node-hello", settings: { background: "paper" } }),
+      // The custom section: the editor's own rows of columns, rendered by Smoodly.
+      custom,
+    ],
+  },
+};
+
+// The home page exists in every locale already (its registration says so): write the tree and publish.
+for (const locale of [DEFAULT, ...OTHERS]) {
+  await c.pages.setTree(home.id, locale, tree);
+  await c.pages.publish(home.id, locale);
+}
+
+console.log(`Seeded the blank starter in "${[DEFAULT, ...OTHERS].join('", "')}": the home page and the site item, published.`);

package/templates/astro-blank/src/components/LocaleNav.astro

@@ -0,0 +1,15 @@
+---
+// src/components/LocaleNav.astro — the language links, rendered by every page view from its own `locales` map:
+// the same page in the other language where it is published there, that language's home otherwise. Nothing
+// with one locale, so the single-language scaffold shares the file.
+import { href } from "smoodly/astro/runtime";
+
+type Props = { locale: string; locales: Record<string, { path: string | null } | null> };
+const { locale, locales } = Astro.props;
+const codes = Object.keys(locales);
+---
+{codes.length > 1 && (
+  <nav class="container locales" aria-label="Language">
+    {codes.map((code) => <a href={href(locales[code]?.path ?? "/", code)} aria-current={code === locale ? "page" : undefined}>{code}</a>)}
+  </nav>
+)}