@cancia/astro 0.0.2 → 0.1.0

package/dist/chunk-BOIQNZAO.js

@@ -0,0 +1,64 @@
+// src/schema/portable-text.ts
+import { z } from "zod";
+var PT_STYLES = ["normal", "h2", "h3", "blockquote"];
+var PT_LIST_ITEMS = ["bullet", "number"];
+var PT_DECORATORS = ["strong", "em"];
+function isSafeHref(href) {
+  if (typeof href !== "string") return false;
+  const trimmed = href.trim();
+  if (trimmed === "") return false;
+  if (/^(https?:|mailto:|tel:)/i.test(trimmed)) return true;
+  const schemeMatch = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+  if (schemeMatch) {
+    const beforeColon = trimmed.slice(0, schemeMatch[1].length);
+    const firstSep = trimmed.search(/[/?#]/);
+    const colonIndex = beforeColon.length;
+    if (firstSep === -1 || colonIndex < firstSep) return false;
+  }
+  return true;
+}
+var ptLinkMarkDefSchema = z.object({
+  _type: z.literal("link"),
+  _key: z.string(),
+  href: z.string().refine(isSafeHref, "unsafe or unsupported URL scheme")
+});
+var ptSpanSchema = z.object({
+  _type: z.literal("span"),
+  _key: z.string(),
+  text: z.string(),
+  marks: z.array(z.string())
+});
+var ptBlockSchema = z.object({
+  _type: z.literal("block"),
+  _key: z.string(),
+  style: z.enum(PT_STYLES),
+  listItem: z.enum(PT_LIST_ITEMS).optional(),
+  level: z.number().int().positive().optional(),
+  markDefs: z.array(ptLinkMarkDefSchema).default([]),
+  children: z.array(ptSpanSchema)
+}).superRefine((block, ctx) => {
+  const defKeys = new Set(block.markDefs.map((d) => d._key));
+  const decorators = new Set(PT_DECORATORS);
+  for (const span of block.children) {
+    for (const mark of span.marks) {
+      if (decorators.has(mark)) continue;
+      if (!defKeys.has(mark)) {
+        ctx.addIssue({
+          code: "custom",
+          message: `Mark "${mark}" is not an allowed decorator and does not reference a link markDef`,
+          path: ["children"]
+        });
+      }
+    }
+  }
+});
+var portableTextSubsetSchema = z.array(ptBlockSchema);
+
+export {
+  PT_STYLES,
+  PT_LIST_ITEMS,
+  PT_DECORATORS,
+  isSafeHref,
+  ptBlockSchema,
+  portableTextSubsetSchema
+};

package/dist/{chunk-KL2YMBFV.js → chunk-IIGDU5SV.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-NG5GJME5.js";
 import {
   describeList
-} from "./chunk-RKHJNQ6R.js";
+} from "./chunk-MCHQV6Y7.js";
 
 // src/routes/schemas.ts
 function json(body, status = 200) {

package/dist/{chunk-RKHJNQ6R.js → chunk-MCHQV6Y7.js}

@@ -1,3 +1,7 @@
+import {
+  portableTextSubsetSchema
+} from "./chunk-BOIQNZAO.js";
+
 // src/schema/index.ts
 import { z } from "zod";
 function defineList(opts) {
@@ -26,13 +30,56 @@ var defineField = {
   },
   slug: (o) => z.string().regex(/^[a-z0-9-]+$/).meta({ widget: "slug", ...o }),
   image: (o) => z.string().url().meta({ widget: "image", ...o }),
-  select: (o) => z.enum(o.options).meta({ widget: "select", ...o })
+  select: (o) => z.enum(o.options).meta({ widget: "select", ...o }),
+  /**
+   * A repeatable list of a single member type. `member` is any Zod type,
+   * typically another `defineField.*` (so it keeps its own `.meta({ widget })`
+   * and recursion carries labels/widgets into each row).
+   *
+   *   bullets: f.array(f.text({ label: "Point" }), { label: "Key points" }),
+   *   faqs:    f.array(f.object({ q: f.text(), a: f.textarea() })),
+   */
+  array: (member, o) => z.array(member).meta({ widget: "array", ...o }),
+  /**
+   * A nested group of named sub-fields, rendered as a collapsible fieldset.
+   *
+   *   socials: f.object({ linkedin: f.url(), twitter: f.url() }, { label: "Socials" }),
+   */
+  object: (shape, o) => z.object(shape).meta({ widget: "object", ...o }),
+  /**
+   * A pointer to an entry in another list. Stored as a plain string — the
+   * target entry's id. Per the v0.1.0 design (D5) there is NO integrity
+   * backend: dangling ids are tolerated and surfaced by the editor, never
+   * prevented. `list` is the target list's name (a key in the schemas module).
+   *
+   *   author:  f.reference({ list: "people", label: "Author" }),
+   *   related: f.array(f.reference({ list: "posts" }), { label: "Related" }),
+   */
+  reference: (o) => z.string().meta({ widget: "reference", ...o }),
+  /**
+   * A constrained rich-text body. Stored as a Portable-Text SUBSET array (D4):
+   * block styles normal/h2/h3/blockquote, bullet/number lists, strong/em marks,
+   * and link annotations — nothing else. The toolbar renders a structured block
+   * editor (approach B) over it, and `<CanciaRichText>` renders it to HTML.
+   *
+   *   body: f.richtext({ label: "Body" }),
+   *
+   * The JSON-Schema type of this field is "array"; the explicit
+   * `widget: "richtext"` meta is what distinguishes it from a plain array in
+   * describeProperty.
+   */
+  richtext: (o) => portableTextSubsetSchema.meta({ widget: "richtext", ...o })
 };
+function slugify(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+}
 function humanise(name) {
   return name.replace(/([A-Z])/g, " $1").replace(/[_-]/g, " ").replace(/^\w/, (c) => c.toUpperCase()).trim();
 }
 function inferWidget(prop, label) {
   if (prop.widget) return prop.widget;
+  if (prop.type === "array") return "array";
+  if (prop.type === "object") return "object";
   if (prop.enum) return "select";
   if (prop.type === "boolean") return "checkbox";
   if (prop.type === "number" || prop.type === "integer") return "number";
@@ -64,6 +111,19 @@ function describeProperty(name, prop, required) {
   else if (prop.options) desc.options = prop.options;
   if (prop.pattern !== void 0) desc.pattern = prop.pattern;
   if (prop.source !== void 0) desc.source = prop.source;
+  if (desc.widget === "reference" && prop.list !== void 0) desc.referenceList = prop.list;
+  if (desc.widget === "richtext") {
+    return desc;
+  }
+  if (desc.widget === "array" && prop.items) {
+    desc.of = describeProperty("", prop.items, true);
+  }
+  if (desc.widget === "object" && prop.properties) {
+    const subRequired = new Set(prop.required ?? []);
+    desc.fields = Object.keys(prop.properties).map(
+      (subName) => describeProperty(subName, prop.properties[subName], subRequired.has(subName))
+    );
+  }
   return desc;
 }
 function describeList(name, schema) {
@@ -90,5 +150,6 @@ export {
   z,
   defineList,
   defineField,
+  slugify,
   describeList
 };

package/dist/endpoints/schemas.js

@@ -1,8 +1,9 @@
 import {
   makeSchemasRoute
-} from "../chunk-KL2YMBFV.js";
+} from "../chunk-IIGDU5SV.js";
 import "../chunk-NG5GJME5.js";
-import "../chunk-RKHJNQ6R.js";
+import "../chunk-MCHQV6Y7.js";
+import "../chunk-BOIQNZAO.js";
 
 // src/endpoints/schemas.ts
 import { getCanciaRuntime } from "virtual:cancia/runtime";

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { FieldDescription, FieldMeta, FieldMetaBase, FieldWidget, ListDescriptio
 export { createJsonFileAdapter, createJsonFileAdapterV2, createSQLiteAdapter } from './storage/index.js';
 export { z } from 'zod';
 import 'astro/loaders';
+import './portable-text-BikSqS9T.js';
 
 interface R2UploadHandlerOptions {
     /** Cloudflare account ID (from R2 dashboard) */

package/dist/index.js

@@ -3,7 +3,7 @@ import {
 } from "./chunk-22DJVJBR.js";
 import {
   makeSchemasRoute
-} from "./chunk-KL2YMBFV.js";
+} from "./chunk-IIGDU5SV.js";
 import "./chunk-NG5GJME5.js";
 import {
   setCanciaRuntime
@@ -13,7 +13,7 @@ import {
   defineList,
   describeList,
   z
-} from "./chunk-RKHJNQ6R.js";
+} from "./chunk-MCHQV6Y7.js";
 import {
   canciaLoader
 } from "./chunk-337LJIKX.js";
@@ -27,6 +27,7 @@ import {
 import {
   RevConflictError
 } from "./chunk-7IA5B5CF.js";
+import "./chunk-BOIQNZAO.js";
 import {
   detectImageType,
   isValidSite

package/dist/portable-text-BikSqS9T.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+
+/** The four block styles the subset permits. */
+declare const PT_STYLES: readonly ["normal", "h2", "h3", "blockquote"];
+type PtStyle = (typeof PT_STYLES)[number];
+/** The two list kinds the subset permits (absent = not a list item). */
+declare const PT_LIST_ITEMS: readonly ["bullet", "number"];
+type PtListItem = (typeof PT_LIST_ITEMS)[number];
+/** The two decorators (marks that are not annotation keys) the subset permits. */
+declare const PT_DECORATORS: readonly ["strong", "em"];
+type PtDecorator = (typeof PT_DECORATORS)[number];
+/**
+ * Whether a link href uses a SAFE scheme. This is the XSS gate for the only
+ * annotation the subset carries: astro-portabletext renders `href` straight
+ * into an <a href> without scheme filtering, so a link authored as
+ * `javascript:alert(1)` or `data:text/html,…` would be a live injection vector
+ * — exactly what the "no raw HTML" design (D4) exists to prevent. Only allow:
+ *   - http(s), mailto:, tel: absolute URLs
+ *   - root-relative (`/…`), fragment (`#…`), and relative (`./…`, `../…`, or a
+ *     bare path) links that carry NO scheme at all.
+ * Everything with any other scheme (javascript:, data:, vbscript:, file:, …)
+ * is rejected. Exported so the parser and tests share one definition.
+ */
+declare function isSafeHref(href: string): boolean;
+/**
+ * A link annotation. Stored in a block's `markDefs`; a span references it by
+ * putting the markDef's `_key` in its `marks` array. `href` is the only
+ * carried property (no title/target — kept minimal and sanitizable), and it is
+ * constrained to safe schemes (see isSafeHref) so a stored value can never
+ * carry a javascript:/data: XSS payload.
+ */
+declare const ptLinkMarkDefSchema: z.ZodObject<{
+    _type: z.ZodLiteral<"link">;
+    _key: z.ZodString;
+    href: z.ZodString;
+}, z.core.$strip>;
+type PtLinkMarkDef = z.infer<typeof ptLinkMarkDefSchema>;
+/**
+ * A text span. `marks` entries are EITHER a decorator ("strong"/"em") OR a
+ * markDef `_key` present in the parent block's `markDefs`. We validate the
+ * decorator-or-string shape here; the cross-reference (every non-decorator mark
+ * resolves to a markDef) is enforced by the refine on the block below.
+ */
+declare const ptSpanSchema: z.ZodObject<{
+    _type: z.ZodLiteral<"span">;
+    _key: z.ZodString;
+    text: z.ZodString;
+    marks: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type PtSpan = z.infer<typeof ptSpanSchema>;
+/**
+ * A single block. `listItem`/`level` are present only for list rows. Every
+ * span mark that is not a decorator must reference a link markDef by key —
+ * that guard is what keeps arbitrary annotations out of the stored value.
+ */
+declare const ptBlockSchema: z.ZodObject<{
+    _type: z.ZodLiteral<"block">;
+    _key: z.ZodString;
+    style: z.ZodEnum<{
+        normal: "normal";
+        h2: "h2";
+        h3: "h3";
+        blockquote: "blockquote";
+    }>;
+    listItem: z.ZodOptional<z.ZodEnum<{
+        number: "number";
+        bullet: "bullet";
+    }>>;
+    level: z.ZodOptional<z.ZodNumber>;
+    markDefs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        _type: z.ZodLiteral<"link">;
+        _key: z.ZodString;
+        href: z.ZodString;
+    }, z.core.$strip>>>;
+    children: z.ZodArray<z.ZodObject<{
+        _type: z.ZodLiteral<"span">;
+        _key: z.ZodString;
+        text: z.ZodString;
+        marks: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type PtBlock = z.infer<typeof ptBlockSchema>;
+/**
+ * The stored rich-text value: an array of subset blocks. Attach
+ * `.meta({ widget: "richtext" })` in defineField so describeList can identify
+ * it (its JSON-Schema type is "array", so the explicit widget is the only
+ * reliable signal — see the guard in describeProperty).
+ */
+declare const portableTextSubsetSchema: z.ZodArray<z.ZodObject<{
+    _type: z.ZodLiteral<"block">;
+    _key: z.ZodString;
+    style: z.ZodEnum<{
+        normal: "normal";
+        h2: "h2";
+        h3: "h3";
+        blockquote: "blockquote";
+    }>;
+    listItem: z.ZodOptional<z.ZodEnum<{
+        number: "number";
+        bullet: "bullet";
+    }>>;
+    level: z.ZodOptional<z.ZodNumber>;
+    markDefs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        _type: z.ZodLiteral<"link">;
+        _key: z.ZodString;
+        href: z.ZodString;
+    }, z.core.$strip>>>;
+    children: z.ZodArray<z.ZodObject<{
+        _type: z.ZodLiteral<"span">;
+        _key: z.ZodString;
+        text: z.ZodString;
+        marks: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+type PortableTextValue = z.infer<typeof portableTextSubsetSchema>;
+
+export { PT_DECORATORS as P, PT_LIST_ITEMS as a, PT_STYLES as b, type PortableTextValue as c, type PtBlock as d, type PtDecorator as e, type PtLinkMarkDef as f, type PtListItem as g, type PtSpan as h, type PtStyle as i, isSafeHref as j, ptBlockSchema as k, portableTextSubsetSchema as p };

package/dist/richtext/CanciaRichText.astro

@@ -0,0 +1,44 @@
+---
+// =============================================================================
+// <CanciaRichText> — render a Cancia rich-text (Portable-Text SUBSET) value
+// =============================================================================
+// Renders the stored PT-subset array (see schema/portable-text.ts) to real
+// HTML using astro-portabletext. The subset — normal/h2/h3/blockquote blocks,
+// bullet/number lists, strong/em marks, link annotations — is a strict subset
+// of Portable Text, so astro-portabletext's DEFAULT components already cover
+// every case; we only override `link` to add rel/target hardening for external
+// hrefs. There is no raw HTML in the value (D4), so nothing is dangerouslySet.
+//
+// Usage in a page/template:
+//   ---
+//   import CanciaRichText from "@cancia/astro/richtext/CanciaRichText.astro";
+//   const { body } = entry.data;
+//   ---
+//   <CanciaRichText value={body} />
+//
+// This file ships as a raw .astro under dist/richtext/ (an .astro file can't be
+// a tsup entry) and is Vite-free at the package boundary — importing it does
+// NOT pull in the Cancia integration.
+// =============================================================================
+import { PortableText } from "astro-portabletext";
+import Link from "./Link.astro";
+
+export interface Props {
+  /** The stored PT-subset value. Undefined / empty renders nothing. */
+  value?: unknown;
+}
+
+const { value } = Astro.props;
+
+// Normalise: only render for a non-empty array of blocks. undefined, null, or
+// [] all render nothing (empty-value handling — [] vs undefined both no-op).
+const blocks = Array.isArray(value) ? value : [];
+---
+
+{
+  blocks.length > 0 && (
+    <div class="cancia-richtext">
+      <PortableText value={blocks} components={{ mark: { link: Link } }} />
+    </div>
+  )
+}

package/dist/richtext/Link.astro

@@ -0,0 +1,25 @@
+---
+// =============================================================================
+// Link mark for <CanciaRichText>
+// =============================================================================
+// astro-portabletext hands a mark component the resolved markDef on `node`. For
+// the subset's only annotation (link) that markDef is { _type:"link", href }.
+// We render an <a> and harden EXTERNAL hrefs (anything with a scheme) with
+// rel="noopener noreferrer" + target="_blank"; in-page/relative links stay
+// plain. The href is a plain string from the validated value — never HTML.
+// =============================================================================
+const { node } = Astro.props as {
+  node: { markDef?: { href?: string } };
+};
+
+const href = node?.markDef?.href ?? "#";
+const isExternal = /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("//");
+---
+
+{
+  isExternal ? (
+    <a href={href} rel="noopener noreferrer" target="_blank"><slot /></a>
+  ) : (
+    <a href={href}><slot /></a>
+  )
+}

package/dist/richtext/index.d.ts

@@ -0,0 +1,23 @@
+import { i as PtStyle, g as PtListItem, d as PtBlock } from '../portable-text-BikSqS9T.js';
+export { P as PT_DECORATORS, a as PT_LIST_ITEMS, b as PT_STYLES, c as PortableTextValue, e as PtDecorator, f as PtLinkMarkDef, h as PtSpan, j as isSafeHref, p as portableTextSubsetSchema, k as ptBlockSchema } from '../portable-text-BikSqS9T.js';
+import 'zod';
+
+/** A row as the editor holds it: raw shorthand text + style + optional list kind. */
+interface RichTextRow {
+    text: string;
+    style: PtStyle;
+    listItem?: PtListItem;
+}
+/**
+ * Turn one editor row into a PT-subset block. Empty text still yields a block
+ * with a single empty span (PT convention) so the row survives a round-trip.
+ */
+declare function rowToBlock(row: RichTextRow): PtBlock;
+/** Serialise a list of editor rows into a PT-subset value (block array). */
+declare function rowsToPortableText(rows: RichTextRow[]): PtBlock[];
+/** Turn a PT-subset block back into an editable row (text + style + list). */
+declare function blockToRow(block: PtBlock): RichTextRow;
+/** Deserialise a PT-subset value into editor rows. */
+declare function portableTextToRows(value: PtBlock[]): RichTextRow[];
+
+export { PtBlock, PtListItem, PtStyle, type RichTextRow, blockToRow, portableTextToRows, rowToBlock, rowsToPortableText };

package/dist/richtext/index.js

@@ -0,0 +1,142 @@
+import {
+  PT_DECORATORS,
+  PT_LIST_ITEMS,
+  PT_STYLES,
+  isSafeHref,
+  portableTextSubsetSchema,
+  ptBlockSchema
+} from "../chunk-BOIQNZAO.js";
+
+// src/richtext/markdown.ts
+function keyGen(prefix) {
+  let n = 0;
+  return () => `${prefix}${(n++).toString(36)}`;
+}
+function parseInline(input) {
+  const segments = [];
+  let plain = "";
+  let i = 0;
+  const flushPlain = () => {
+    if (plain) {
+      segments.push({ text: plain, marks: [] });
+      plain = "";
+    }
+  };
+  while (i < input.length) {
+    if (input[i] === "\\" && i + 1 < input.length) {
+      plain += input[i + 1];
+      i += 2;
+      continue;
+    }
+    if (input[i] === "[") {
+      const close = input.indexOf("]", i + 1);
+      if (close !== -1 && input[close + 1] === "(") {
+        const paren = input.indexOf(")", close + 2);
+        if (paren !== -1) {
+          const text = input.slice(i + 1, close);
+          const href = input.slice(close + 2, paren);
+          flushPlain();
+          segments.push({ text, marks: [], href });
+          i = paren + 1;
+          continue;
+        }
+      }
+    }
+    if (input[i] === "*" && input[i + 1] === "*") {
+      const end = input.indexOf("**", i + 2);
+      if (end !== -1 && end > i + 2) {
+        flushPlain();
+        segments.push({ text: input.slice(i + 2, end), marks: ["strong"] });
+        i = end + 2;
+        continue;
+      }
+    }
+    if (input[i] === "*") {
+      const end = input.indexOf("*", i + 1);
+      if (end !== -1 && end > i + 1) {
+        flushPlain();
+        segments.push({ text: input.slice(i + 1, end), marks: ["em"] });
+        i = end + 1;
+        continue;
+      }
+    }
+    plain += input[i];
+    i += 1;
+  }
+  flushPlain();
+  return segments;
+}
+function rowToBlock(row) {
+  const spanKey = keyGen("s");
+  const linkKey = keyGen("l");
+  const segments = parseInline(row.text);
+  const markDefs = [];
+  const children = [];
+  for (const seg of segments) {
+    const marks = [...seg.marks];
+    if (seg.href !== void 0 && isSafeHref(seg.href)) {
+      const _key = linkKey();
+      markDefs.push({ _type: "link", _key, href: seg.href });
+      marks.push(_key);
+    }
+    children.push({ _type: "span", _key: spanKey(), text: seg.text, marks });
+  }
+  if (children.length === 0) {
+    children.push({ _type: "span", _key: spanKey(), text: "", marks: [] });
+  }
+  const style = PT_STYLES.includes(row.style) ? row.style : "normal";
+  const block = {
+    _type: "block",
+    _key: keyGen("b")(),
+    style,
+    markDefs,
+    children
+  };
+  if (row.listItem && PT_LIST_ITEMS.includes(row.listItem)) {
+    block.listItem = row.listItem;
+    block.level = 1;
+  }
+  return block;
+}
+function rowsToPortableText(rows) {
+  return rows.map(rowToBlock);
+}
+function escapeShorthand(text) {
+  return text.replace(/([\\*\[\]])/g, "\\$1");
+}
+function spanToShorthand(span, linkHrefByKey) {
+  let out = escapeShorthand(span.text);
+  const href = span.marks.map((m) => linkHrefByKey.get(m)).find((h) => h !== void 0);
+  if (href !== void 0) out = `[${out}](${href})`;
+  if (span.marks.includes("strong")) out = `**${out}**`;
+  if (span.marks.includes("em")) out = `*${out}*`;
+  return out;
+}
+function blockToRow(block) {
+  const linkHrefByKey = /* @__PURE__ */ new Map();
+  for (const def of block.markDefs ?? []) {
+    if (def._type === "link") linkHrefByKey.set(def._key, def.href);
+  }
+  const text = (block.children ?? []).map((span) => spanToShorthand(span, linkHrefByKey)).join("");
+  const row = {
+    text,
+    style: PT_STYLES.includes(block.style) ? block.style : "normal"
+  };
+  if (block.listItem && PT_LIST_ITEMS.includes(block.listItem)) row.listItem = block.listItem;
+  return row;
+}
+function portableTextToRows(value) {
+  return value.map(blockToRow);
+}
+export {
+  PT_DECORATORS,
+  PT_LIST_ITEMS,
+  PT_STYLES,
+  blockToRow,
+  isSafeHref,
+  portableTextSubsetSchema,
+  portableTextToRows,
+  ptBlockSchema,
+  rowToBlock,
+  rowsToPortableText
+};

package/dist/schema/index.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 export { z } from 'zod';
+export { P as PT_DECORATORS, a as PT_LIST_ITEMS, b as PT_STYLES, c as PortableTextValue, d as PtBlock, e as PtDecorator, f as PtLinkMarkDef, g as PtListItem, h as PtSpan, i as PtStyle, j as isSafeHref, p as portableTextSubsetSchema, k as ptBlockSchema } from '../portable-text-BikSqS9T.js';
 
 /**
  * Widget hint the modal form uses to pick an input element. The Zod type
@@ -15,7 +16,7 @@ export { z } from 'zod';
  *   z.boolean()          → "checkbox"
  *   z.enum([...])        → "select"
  */
-type FieldWidget = "text" | "textarea" | "url" | "email" | "datetime" | "number" | "checkbox" | "select" | "image" | "slug";
+type FieldWidget = "text" | "textarea" | "url" | "email" | "datetime" | "number" | "checkbox" | "select" | "image" | "slug" | "array" | "object" | "reference" | "richtext";
 /**
  * Fields common to every widget's metadata. All optional.
  */
@@ -51,6 +52,15 @@ type FieldMeta = (FieldMetaBase & {
 }) | (FieldMetaBase & {
     widget: "slug";
     source?: string;
+}) | (FieldMetaBase & {
+    widget: "array";
+}) | (FieldMetaBase & {
+    widget: "object";
+}) | (FieldMetaBase & {
+    widget: "reference";
+    list: string;
+}) | (FieldMetaBase & {
+    widget: "richtext";
 });
 interface ListSchemaOptions<TFields extends Record<string, z.ZodTypeAny>> {
     /** Display label for the list (e.g. "Blog Posts"). */
@@ -106,6 +116,15 @@ interface FieldDescription {
     pattern?: string;
     /** For slug widgets: the field name to auto-generate the slug from. */
     source?: string;
+    /**
+     * For array widgets: the description of a single item. The item has no name
+     * of its own (arrays are keyed by position), so `of.name` is "".
+     */
+    of?: FieldDescription;
+    /** For object widgets: the sub-field descriptions, in declared order. */
+    fields?: FieldDescription[];
+    /** For reference widgets: the name of the list whose entries this points at. */
+    referenceList?: string;
 }
 /**
  * Typed field constructors. Each returns the underlying Zod type with a
@@ -148,6 +167,71 @@ declare const defineField: {
     }) => z.ZodEnum<{
         [x: string]: string;
     }>;
+    /**
+     * A repeatable list of a single member type. `member` is any Zod type,
+     * typically another `defineField.*` (so it keeps its own `.meta({ widget })`
+     * and recursion carries labels/widgets into each row).
+     *
+     *   bullets: f.array(f.text({ label: "Point" }), { label: "Key points" }),
+     *   faqs:    f.array(f.object({ q: f.text(), a: f.textarea() })),
+     */
+    array: <TMember extends z.ZodTypeAny>(member: TMember, o?: FieldMetaBase) => z.ZodArray<TMember>;
+    /**
+     * A nested group of named sub-fields, rendered as a collapsible fieldset.
+     *
+     *   socials: f.object({ linkedin: f.url(), twitter: f.url() }, { label: "Socials" }),
+     */
+    object: <TShape extends Record<string, z.ZodTypeAny>>(shape: TShape, o?: FieldMetaBase) => z.ZodObject<{ -readonly [P in keyof TShape]: TShape[P]; }, z.core.$strip>;
+    /**
+     * A pointer to an entry in another list. Stored as a plain string — the
+     * target entry's id. Per the v0.1.0 design (D5) there is NO integrity
+     * backend: dangling ids are tolerated and surfaced by the editor, never
+     * prevented. `list` is the target list's name (a key in the schemas module).
+     *
+     *   author:  f.reference({ list: "people", label: "Author" }),
+     *   related: f.array(f.reference({ list: "posts" }), { label: "Related" }),
+     */
+    reference: (o: FieldMetaBase & {
+        list: string;
+    }) => z.ZodString;
+    /**
+     * A constrained rich-text body. Stored as a Portable-Text SUBSET array (D4):
+     * block styles normal/h2/h3/blockquote, bullet/number lists, strong/em marks,
+     * and link annotations — nothing else. The toolbar renders a structured block
+     * editor (approach B) over it, and `<CanciaRichText>` renders it to HTML.
+     *
+     *   body: f.richtext({ label: "Body" }),
+     *
+     * The JSON-Schema type of this field is "array"; the explicit
+     * `widget: "richtext"` meta is what distinguishes it from a plain array in
+     * describeProperty.
+     */
+    richtext: (o?: PlainFieldOptions) => z.ZodArray<z.ZodObject<{
+        _type: z.ZodLiteral<"block">;
+        _key: z.ZodString;
+        style: z.ZodEnum<{
+            normal: "normal";
+            h2: "h2";
+            h3: "h3";
+            blockquote: "blockquote";
+        }>;
+        listItem: z.ZodOptional<z.ZodEnum<{
+            number: "number";
+            bullet: "bullet";
+        }>>;
+        level: z.ZodOptional<z.ZodNumber>;
+        markDefs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            _type: z.ZodLiteral<"link">;
+            _key: z.ZodString;
+            href: z.ZodString;
+        }, z.core.$strip>>>;
+        children: z.ZodArray<z.ZodObject<{
+            _type: z.ZodLiteral<"span">;
+            _key: z.ZodString;
+            text: z.ZodString;
+            marks: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 };
 interface ListDescription {
     name: string;
@@ -158,8 +242,22 @@ interface ListDescription {
     slugField?: string;
     fields: FieldDescription[];
 }
+/**
+ * Turn arbitrary text into a URL-safe slug: lowercase, spaces → hyphens,
+ * strip anything outside [a-z0-9-], collapse runs of hyphens, trim leading
+ * and trailing hyphens. Matches the slug field regex `^[a-z0-9-]+$`.
+ *
+ * Used by the toolbar to auto-derive a slug from a title as the editor types
+ * (plan 025). Kept here (not in the toolbar) so it is unit-tested alongside the
+ * schema helpers and stays the single definition of "what a slug looks like".
+ *
+ *   slugify("Hello, World!")   → "hello-world"
+ *   slugify("  Multiple   spaces ") → "multiple-spaces"
+ *   slugify("Café déjà vu")    → "caf-dj-vu"  (non-ASCII stripped)
+ */
+declare function slugify(input: string): string;
 declare function describeList(name: string, schema: ListSchema): ListDescription;
 /** Map of list name → schema. What users export from src/cms/schemas.ts. */
 type SchemasModule = Record<string, ListSchema>;
 
-export { type FieldDescription, type FieldMeta, type FieldMetaBase, type FieldWidget, type ListDescription, type ListSchema, type ListSchemaOptions, type SchemasModule, defineField, defineList, describeList };
+export { type FieldDescription, type FieldMeta, type FieldMetaBase, type FieldWidget, type ListDescription, type ListSchema, type ListSchemaOptions, type SchemasModule, defineField, defineList, describeList, slugify };

package/dist/schema/index.js

@@ -2,11 +2,27 @@ import {
   defineField,
   defineList,
   describeList,
+  slugify,
   z
-} from "../chunk-RKHJNQ6R.js";
+} from "../chunk-MCHQV6Y7.js";
+import {
+  PT_DECORATORS,
+  PT_LIST_ITEMS,
+  PT_STYLES,
+  isSafeHref,
+  portableTextSubsetSchema,
+  ptBlockSchema
+} from "../chunk-BOIQNZAO.js";
 export {
+  PT_DECORATORS,
+  PT_LIST_ITEMS,
+  PT_STYLES,
   defineField,
   defineList,
   describeList,
+  isSafeHref,
+  portableTextSubsetSchema,
+  ptBlockSchema,
+  slugify,
   z
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cancia/astro",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Astro integration for Cancia CMS — inline editing with zero separate server",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,12 @@
     "./storage": {
       "types": "./dist/storage/index.d.ts",
       "import": "./dist/storage/index.js"
-    }
+    },
+    "./richtext": {
+      "types": "./dist/richtext/index.d.ts",
+      "import": "./dist/richtext/index.js"
+    },
+    "./richtext/CanciaRichText.astro": "./dist/richtext/CanciaRichText.astro"
   },
   "files": [
     "dist"
@@ -54,6 +59,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
+    "astro-portabletext": "^0.13.0",
     "zod": "^4.4.3"
   },
   "scripts": {