astroidjs 0.1.0

package/dist/worker/routes.js

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The editor route plan — which louise-toolkit/editor routes a project needs, in
+// the ONE order that avoids matcher collisions. This is where the "versionsRoute
+// and searchRoute MUST precede pagesRoute" tribal knowledge lives: encoded once,
+// as data, instead of re-derived by hand (and mis-ordered) in every site's
+// worker.ts. The generator turns this plan into source; tests assert the order.
+import { capturesInquiries } from "../schema/framework.js";
+/**
+ * The ordered editor route plan for a project. Order is load-bearing: the two
+ * routes with `/pages/:id/...` sub-paths (`versions`, `search`) come first, so
+ * `pages`' catch-all `/:id` matcher can't swallow them. Inquiry routes are
+ * included only when a brand captures inquiries; `seed` is always last.
+ */
+export function astroidEditorRoutePlan(config) {
+    const routes = [
+        {
+            name: "versions",
+            factory: "versionsRoute",
+            note: "Draft/publish + version history for pages. MUST precede pagesRoute — pagesRoute's /:id matcher would otherwise claim /pages/:id/versions and 400 on the non-integer id.",
+        },
+        {
+            name: "search",
+            factory: "searchRoute",
+            note: "Full-text search over pages (/search + /reindex). Before pagesRoute, whose /:id matcher would else claim those non-integer segments.",
+        },
+        {
+            name: "pages",
+            factory: "pagesRoute",
+            note: "Page CRUD, including the structured sections column.",
+        },
+        {
+            name: "save",
+            factory: "saveRoute",
+            note: "Live field saves (title, SEO) — the versioned body stages drafts via versionsRoute instead.",
+        },
+        {
+            name: "settings",
+            factory: "settingsRoute",
+            note: "Editable site settings (brand, nav, contact, SEO defaults).",
+        },
+        {
+            name: "media",
+            factory: "mediaRoute",
+            note: "Media library — list, upload, delete, reference checks.",
+        },
+        {
+            name: "editors",
+            factory: "editorsRoute",
+            note: "Editor roster (the Users panel) over Better Auth's `user` table — a row IS an editor, and the same table is the magic-link allowlist (resolveAdmins).",
+        },
+    ];
+    if (capturesInquiries(config)) {
+        routes.push({
+            name: "form",
+            factory: "formRoute",
+            note: "Public inquiry capture (the contact form) + silent spam heuristics.",
+        }, {
+            name: "inquiries",
+            factory: "inquiriesRoute",
+            note: "Editor-gated inquiry review, over the same inquiries table.",
+        });
+    }
+    routes.push({
+        name: "seed",
+        factory: "seedRoute",
+        note: "First-run site_settings seed. Last — it's a one-shot bootstrap, not a hot path.",
+    });
+    return routes;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "astroidjs",
+  "version": "0.1.0",
+  "description": "Astroid — an opinionated meta-framework over Louise Toolkit and Astro for building editable, multi-editor sites on Cloudflare Workers.",
+  "keywords": [
+    "astro",
+    "cloudflare-workers",
+    "cms",
+    "commerce",
+    "louise-toolkit",
+    "meta-framework"
+  ],
+  "license": "MIT",
+  "author": "BowenLabs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bowenlabs/louise-toolkit.git",
+    "directory": "packages/astroid"
+  },
+  "type": "module",
+  "bin": {
+    "astroid": "./bin/astroid.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./components/*.astro": "./src/components/*.astro",
+    "./components/Collection": {
+      "types": "./src/components/Collection.tsx",
+      "default": "./src/components/Collection.tsx"
+    },
+    "./components/sections": {
+      "types": "./src/components/sections.ts",
+      "default": "./src/components/sections.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src/components"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "louise-toolkit": "0.14.0"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "solid-js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "solid-js": "^1.9.14",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "typecheck": "tsgo --noEmit"
+  }
+}

package/src/components/Collection.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// `<Collection>` — the typed list primitive (ADR 0003, item 3). It renders a list
+// and hands each item to a render function that is FULLY TYPED, with no
+// hand-written interface: the item type is inferred from `items`, so `item` in the
+// slot carries whatever shape you passed.
+//
+//   <Collection items={artworks}>
+//     {(art) => <WorkTile title={art.title} price={art.price} />}
+//   </Collection>
+//
+// Why a Solid render-prop and not an `.astro` component: Astro slots can't type a
+// per-item `{item}`, but a Solid children-as-function can — this is the only shape
+// that delivers the ADR's "`{item}` in its slot is fully typed". Server-render it
+// by using it inside a Solid island without a `client:*` directive: it emits
+// static HTML and ships no JS. Add `client:load`/`client:visible` only if the list
+// needs interactivity.
+//
+// On the item type + ADR 0003 §6 ("infers from the collection's Zod schema"):
+// Louise's `CollectionConfig` is type-erased (`fields: Record<string,
+// FieldConfig>`), so the item shape can't be recovered from the collection VALUE.
+// Instead you type `items` from your data — per ADR 0001, a Zod-inferred query
+// result — and it flows through to the slot. Same guarantee (a typed `item`),
+// sourced from the data rather than the erased config.
+
+import { For, type JSX } from "solid-js";
+
+export interface CollectionProps<T> {
+  /** The items to render, in order. The item type `T` is inferred from here. */
+  items: readonly T[];
+  /** Render one item — receives the fully-typed `item` and a reactive `index`. */
+  children: (item: T, index: () => number) => JSX.Element;
+  /** Rendered when `items` is empty. */
+  fallback?: JSX.Element;
+}
+
+export function Collection<T>(props: CollectionProps<T>): JSX.Element {
+  return (
+    <For each={props.items} fallback={props.fallback}>
+      {(item, index) => props.children(item, index)}
+    </For>
+  );
+}

package/src/components/Editable.astro

@@ -0,0 +1,71 @@
+---
+// `<Editable>` — the Astroid inline-edit primitive (ADR 0003, checklist item 1).
+//
+// It owns the `data-louise-*` marker contract so sites stop stamping it by hand:
+// in edit mode it renders your element with the markers the Louise client
+// (`mountLouise` / `mountSections`) looks for to make the field editable in place;
+// out of edit mode it renders the element plain, with zero editing attributes in
+// the public HTML.
+//
+// Two flavors, per which surface the field lives on:
+//   • PAGE field  — pass `collection` + `key` + `field`; emits
+//                   `data-louise-field="<collection>:<key>:<field>"` (saved as a
+//                   versioned draft when the page is mounted with `versionedPageId`).
+//   • SECTION field — pass `sfield` (the `<index>.<path>` into the section's data,
+//                   ADR 0003 §5); emits `data-louise-sfield` (+ `data-louise-multiline`),
+//                   for the structured `<Section>` editor.
+//
+// Polymorphic via `as` (default `div`) with a typed `...rest` over the div's
+// attributes; edit mode is read from context (`Astro.locals.editMode`) unless the
+// caller passes `edit` (a section knows its own edit flag).
+import type { HTMLAttributes, HTMLTag } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  /** The element to render. Default `"div"`. */
+  as?: HTMLTag;
+  /** PAGE-field mode: the Louise collection slug (e.g. `"pages"`). */
+  collection?: string;
+  /** PAGE-field mode: the row key/id the field is on. */
+  key?: string | number;
+  /** PAGE-field mode: the field name (e.g. `"title"`, `"body"`). */
+  field?: string;
+  /** SECTION-field mode: the `<index>.<path>` marker for the section editor. */
+  sfield?: string;
+  /** Rich text (ProseKit) vs a single-line contenteditable. Default `"text"`. */
+  type?: "text" | "richtext";
+  /** SECTION-field mode: allow newlines in a plain-text field. */
+  multiline?: boolean;
+  /** Force edit markers on/off. Defaults to `Astro.locals.editMode`. */
+  edit?: boolean;
+}
+
+const {
+  as: Tag = "div",
+  collection,
+  key,
+  field,
+  sfield,
+  type = "text",
+  multiline = false,
+  edit,
+  ...rest
+} = Astro.props;
+
+const editing = edit ?? (Astro.locals as { editMode?: boolean }).editMode ?? false;
+const richText = type === "richtext" ? { "data-louise-type": "richtext" } : {};
+
+let markers: Record<string, string> = {};
+if (editing) {
+  if (sfield) {
+    markers = {
+      "data-louise-sfield": sfield,
+      ...richText,
+      ...(multiline ? { "data-louise-multiline": "" } : {}),
+    };
+  } else if (collection && key !== undefined && field) {
+    markers = { "data-louise-field": `${collection}:${key}:${field}`, ...richText };
+  }
+}
+---
+
+<Tag {...rest} {...markers}><slot /></Tag>

package/src/components/Section.astro

@@ -0,0 +1,46 @@
+---
+// `<Section>` — the section-library dispatcher (ADR 0003, item 2). It's a
+// discriminated union over `SectionKind` (see ./sections.ts): `<Section
+// kind="hero" heading="…" />` requires hero fields and rejects another kind's, and
+// each arm renders the matching section-library component. Bespoke, site-owned
+// sections stay first-class (as the reference site's hand-written ones are) — this
+// is for the catalog sections, not a mandate to route everything through it.
+import type { SectionProps } from "./sections.js";
+import Contact from "./sections/Contact.astro";
+import Cta from "./sections/Cta.astro";
+import FeatureGrid from "./sections/FeatureGrid.astro";
+import Hero from "./sections/Hero.astro";
+
+const p = Astro.props as SectionProps;
+---
+
+{
+  p.kind === "hero" && (
+    <Hero
+      heading={p.heading}
+      subheading={p.subheading}
+      ctaLabel={p.ctaLabel}
+      ctaHref={p.ctaHref}
+      colorway={p.colorway}
+      align={p.align}
+    />
+  )
+}
+{
+  p.kind === "featureGrid" && (
+    <FeatureGrid heading={p.heading} items={p.items} colorway={p.colorway} align={p.align} />
+  )
+}
+{
+  p.kind === "cta" && (
+    <Cta
+      heading={p.heading}
+      body={p.body}
+      ctaLabel={p.ctaLabel}
+      ctaHref={p.ctaHref}
+      colorway={p.colorway}
+      align={p.align}
+    />
+  )
+}
+{p.kind === "contact" && <Contact heading={p.heading} blurb={p.blurb} colorway={p.colorway} align={p.align} />}

package/src/components/sections/Contact.astro

@@ -0,0 +1,18 @@
+---
+// Contact section (ADR 0003, item 4) — a heading + blurb + link to the contact
+// route (the generated worker's contact form lives at /contact).
+import type { ContactFields, SectionBase } from "../sections.js";
+import { colorwayClass } from "../sections.js";
+
+type Props = SectionBase & ContactFields;
+
+const { heading = "Get in touch", blurb, colorway = "base" } = Astro.props;
+---
+
+<section class:list={["py-16", colorwayClass(colorway)]}>
+  <div class="mx-auto max-w-xl px-6 text-center">
+    <h2 class="text-3xl font-bold">{heading}</h2>
+    {blurb && <p class="mt-2 opacity-80">{blurb}</p>}
+    <a class="btn btn-primary mt-6" href="/contact">Contact us</a>
+  </div>
+</section>

package/src/components/sections/Cta.astro

@@ -0,0 +1,17 @@
+---
+// Call-to-action band (ADR 0003, item 4). Defaults to the brand colorway.
+import type { CtaFields, SectionBase } from "../sections.js";
+import { alignClass, colorwayClass } from "../sections.js";
+
+type Props = SectionBase & CtaFields;
+
+const { heading, body, ctaLabel, ctaHref, colorway = "brand", align = "center" } = Astro.props;
+---
+
+<section class:list={["py-16", colorwayClass(colorway)]}>
+  <div class:list={["mx-auto flex max-w-3xl flex-col gap-4 px-6", alignClass(align)]}>
+    <h2 class="text-3xl font-bold">{heading}</h2>
+    {body && <p class="text-lg opacity-90">{body}</p>}
+    <a class="btn" href={ctaHref}>{ctaLabel}</a>
+  </div>
+</section>

package/src/components/sections/FeatureGrid.astro

@@ -0,0 +1,26 @@
+---
+// Feature-grid section (ADR 0003, item 4) — value-prop cards. Declarative
+// props → `Theme` tokens via `colorwayClass`.
+import type { FeatureGridFields, SectionBase } from "../sections.js";
+import { colorwayClass } from "../sections.js";
+
+type Props = SectionBase & FeatureGridFields;
+
+const { heading, items, colorway = "base" } = Astro.props;
+---
+
+<section class:list={["py-16", colorwayClass(colorway)]}>
+  <div class="mx-auto max-w-5xl px-6">
+    {heading && <h2 class="mb-8 text-3xl font-bold">{heading}</h2>}
+    <div class="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+      {items.map((item) => (
+        <div class="card bg-base-100 text-base-content shadow-sm">
+          <div class="card-body">
+            <h3 class="card-title">{item.title}</h3>
+            <p class="opacity-80">{item.body}</p>
+          </div>
+        </div>
+      ))}
+    </div>
+  </div>
+</section>

package/src/components/sections/Hero.astro

@@ -0,0 +1,23 @@
+---
+// Hero section (ADR 0003, item 4). Declarative props → `Theme` tokens via the
+// `colorwayClass` / `alignClass` maps — no raw class names in the prop surface, so
+// a brand re-theme flows through without touching markup.
+import type { HeroFields, SectionBase } from "../sections.js";
+import { alignClass, colorwayClass } from "../sections.js";
+
+type Props = SectionBase & HeroFields;
+
+const { heading, subheading, ctaLabel, ctaHref, colorway = "base", align = "center" } = Astro.props;
+---
+
+<section class:list={["hero py-20", colorwayClass(colorway)]}>
+  <div class:list={["hero-content flex-col", alignClass(align)]}>
+    <div class="max-w-2xl">
+      <h1 class="text-5xl font-bold">{heading}</h1>
+      {subheading && <p class="py-6 text-lg opacity-80">{subheading}</p>}
+      {ctaLabel && ctaHref && (
+        <a class="btn btn-primary" href={ctaHref}>{ctaLabel}</a>
+      )}
+    </div>
+  </div>
+</section>

package/src/components/sections.ts

@@ -0,0 +1,108 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The typed model behind the section-library primitives (ADR 0003). This is the
+// part the ADR's conventions bite hardest on, and the part TypeScript actually
+// checks: variant props are unions, not `string` (§1); callers describe intent
+// (`colorway="brand"`) and the component owns the token→class mapping (§2); those
+// unions are DERIVED from the token maps with `keyof typeof`, so the type and the
+// implementation can't drift (§3); and `<Section>` is a discriminated union over
+// `SectionKind`, each arm carrying its own field shape (§6).
+//
+// The `.astro` components consume these types. Only the marketing-floor kinds have
+// components today (hero / featureGrid / cta / contact); more arms are added here
+// with their component, so an unimplemented `kind` is a compile error rather than
+// a blank render.
+//
+// Self-contained on purpose: this module ships as SOURCE (the `.astro` next to it
+// import it directly), so it must not reach back into astroid's built `src/*` —
+// only siblings + external packages. `SectionKind` from config.ts is therefore not
+// imported here; the runtime guard takes a plain `string`.
+
+/**
+ * Colorway → daisyUI surface classes, keyed to the `Theme.colors` set
+ * (brand/secondary/tertiary) plus the neutral base. The map is the single source:
+ * add a colorway here and {@link Colorway} updates itself (§3).
+ */
+export const COLORWAY_CLASS = {
+  brand: "bg-primary text-primary-content",
+  secondary: "bg-secondary text-secondary-content",
+  tertiary: "bg-accent text-accent-content",
+  base: "bg-base-100 text-base-content",
+} as const;
+export type Colorway = keyof typeof COLORWAY_CLASS;
+
+/** Content alignment → fl/text-alignment utilities. */
+export const ALIGN_CLASS = {
+  start: "text-start items-start",
+  center: "text-center items-center",
+  end: "text-end items-end",
+} as const;
+export type Align = keyof typeof ALIGN_CLASS;
+
+/** Shared presentation props every section arm accepts. */
+export interface SectionBase {
+  /** Surface colorway — a closed set mapped to daisyUI classes, never a raw class. */
+  colorway?: Colorway;
+  /** Content alignment. */
+  align?: Align;
+}
+
+// --- Per-kind field shapes -------------------------------------------------
+// The editable content each section kind renders. Kept minimal + declarative;
+// these are the fields a `sections` JSON entry carries.
+
+export interface HeroFields {
+  heading: string;
+  subheading?: string;
+  ctaLabel?: string;
+  ctaHref?: string;
+}
+
+export interface FeatureGridFields {
+  heading?: string;
+  items: { title: string; body: string }[];
+}
+
+export interface CtaFields {
+  heading: string;
+  body?: string;
+  ctaLabel: string;
+  ctaHref: string;
+}
+
+export interface ContactFields {
+  heading?: string;
+  blurb?: string;
+}
+
+/**
+ * The discriminated union `<Section>` dispatches on (§6). `<Section kind="hero">`
+ * requires {@link HeroFields} and rejects another kind's fields; adding a kind
+ * means adding an arm here and a component to render it. Only the kinds with a
+ * shipped component appear — a subset of the full {@link SectionKind} catalog.
+ */
+export type SectionProps =
+  | (SectionBase & { kind: "hero" } & HeroFields)
+  | (SectionBase & { kind: "featureGrid" } & FeatureGridFields)
+  | (SectionBase & { kind: "cta" } & CtaFields)
+  | (SectionBase & { kind: "contact" } & ContactFields);
+
+/** The section kinds that currently have a section-library component — the `kind`
+ *  discriminants of {@link SectionProps}, so it can't drift from the union. */
+export type RenderableSectionKind = SectionProps["kind"];
+
+/** Type guard: does this section kind have a shipped component? Narrows a plain
+ *  string (a `sections` entry's `kind` at runtime) to a {@link RenderableSectionKind}. */
+export function isRenderableSection(kind: string): kind is RenderableSectionKind {
+  return kind === "hero" || kind === "featureGrid" || kind === "cta" || kind === "contact";
+}
+
+/** Resolve a colorway to its class string (default: neutral base). */
+export function colorwayClass(colorway: Colorway = "base"): string {
+  return COLORWAY_CLASS[colorway];
+}
+
+/** Resolve an alignment to its class string (default: start). */
+export function alignClass(align: Align = "start"): string {
+  return ALIGN_CLASS[align];
+}