@backmatter/core 0.0.13 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {

package/src/api-loader.ts

@@ -1,5 +1,6 @@
 // packages/core/src/api-loader.ts
 import type { BackmatterDoc, BackmatterDocSummary } from "./doc";
+import { encodeDocLocale } from "./path";
 
 export type PublicDocsQuery = {
   branch?: string;
@@ -60,7 +61,7 @@ export async function getDocFromApi(
   query: Pick<PublicDocsQuery, "branch" | "tags"> = {},
 ): Promise<BackmatterDoc | null> {
   const res = await fetch(
-    publicDocsUrl(apiUrl, workspaceId, `/${locale}/${type}/${slug}`, query),
+    publicDocsUrl(apiUrl, workspaceId, `/${encodeDocLocale(locale)}/${type}/${slug}`, query),
     fetchInit(contentToken, query.tags),
   );
   if (res.status === 404) return null;

package/src/block.ts

@@ -94,9 +94,8 @@ export function parseBlockSnapshot(input: unknown): BlockSnapshot {
   for (const [name, fieldRaw] of Object.entries(value.fields as Record<string, unknown>)) {
     try {
       fields[name] = parseFieldSnapshot(fieldRaw);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : "invalid field";
-      throw new Error(`block.fields.${name}: ${msg}`);
+    } catch {
+      // Drop unknown kinds so a stored snapshot still loads.
     }
   }
   return { name: value.name, fields };

package/src/config.ts

@@ -12,6 +12,8 @@ export type BackmatterDirs = {
   mdx?: string;
   /** Folder with one layout default export per model type. Default: "layouts". */
   layouts?: string;
+  /** Folder with one `defineObject` default export per file. Default: "objects". */
+  objects?: string;
 };
 
 export type BackmatterConfig = {
@@ -51,6 +53,7 @@ export const DEFAULT_DIRS: Required<BackmatterDirs> = {
   blocks: "blocks",
   mdx: "mdx",
   layouts: "layouts",
+  objects: "objects",
 };
 export const DEFAULT_LOCALE = "en";
 export const CLOUD_API_URL = "https://api.backmatter.app";
@@ -158,6 +161,7 @@ export function resolveConfig(
       blocks: config.dirs?.blocks ?? DEFAULT_DIRS.blocks,
       mdx: config.dirs?.mdx ?? DEFAULT_DIRS.mdx,
       layouts: config.dirs?.layouts ?? DEFAULT_DIRS.layouts,
+      objects: config.dirs?.objects ?? DEFAULT_DIRS.objects,
     },
   };
 }

package/src/content-committed.ts

@@ -30,7 +30,10 @@ export function revalidateUrl(siteUrl: string): string {
 }
 
 export function contentCacheTags(locale: string, type: string, slug: string): string[] {
-  return [BACKMATTER_CACHE_TAG, `backmatter:${type}`, `backmatter:${locale}:${type}:${slug}`];
+  const identity = locale
+    ? `backmatter:${locale}:${type}:${slug}`
+    : `backmatter:${type}:${slug}`;
+  return [BACKMATTER_CACHE_TAG, `backmatter:${type}`, identity];
 }
 
 export function listCacheTags(type?: string): string[] {
@@ -49,6 +52,7 @@ export function pathsForCommittedDocs(
     const model = byType.get(doc.type);
     if (!model) continue;
     const path = routeFor(model, doc.locale, doc.slug);
+    if (!path) continue;
     if (seen.has(path)) continue;
     seen.add(path);
     paths.push(path);

package/src/doc-ref.ts

@@ -10,11 +10,14 @@ export function parseDocRef(input: unknown): DocRef {
     throw new Error("docRef must be an object");
   }
   const value = input as Record<string, unknown>;
-  for (const key of ["workspaceId", "locale", "type", "slug"] as const) {
+  for (const key of ["workspaceId", "type", "slug"] as const) {
     if (typeof value[key] !== "string" || value[key].length === 0) {
       throw new Error(`docRef.${key} is required`);
     }
   }
+  if (typeof value.locale !== "string") {
+    throw new Error("docRef.locale is required");
+  }
   return {
     workspaceId: value.workspaceId as string,
     locale: value.locale as string,
@@ -25,5 +28,7 @@ export function parseDocRef(input: unknown): DocRef {
 
 /** Relative content path (no workspace prefix) used under head/ and trees/{userId}/. */
 export function docRefPath(ref: DocRef): string {
-  return `${ref.locale}/${ref.type}/${ref.slug}`;
+  return ref.locale
+    ? `${ref.locale}/${ref.type}/${ref.slug}`
+    : `${ref.type}/${ref.slug}`;
 }

package/src/fields.ts

@@ -2,13 +2,14 @@
 
 export type FieldKind =
   | "text"
-  | "slug"
   | "locale"
   | "image"
   | "relation"
   | "number"
   | "boolean"
-  | "blocks";
+  | "blocks"
+  | "object"
+  | "array";
 
 /**
  * Field definition. Generic parameters only exist for type inference
@@ -23,14 +24,22 @@ export type FieldDef<
   required?: R;
   /** For relation fields: target model type. */
   relationTo?: To;
+  /** For object/array fields: named object. */
+  object?: string;
+  /** Nested fields for object/array (inline or copied from defineObject). */
+  fields?: Record<string, FieldDef>;
 };
 
 export type FieldSnapshot = {
   kind: FieldKind;
   required?: boolean;
   relationTo?: string;
+  object?: string;
+  fields?: Record<string, FieldSnapshot>;
 };
 
+type ObjectLike = { name: string; fields: Record<string, FieldDef> };
+
 type Opts<R extends boolean> = { required?: R };
 
 function base<K extends FieldKind, R extends boolean, To extends string>(
@@ -44,9 +53,20 @@ function base<K extends FieldKind, R extends boolean, To extends string>(
   } as FieldDef<K, R, To>;
 }
 
+function composite<K extends "object" | "array", R extends boolean>(
+  kind: K,
+  def: string | ObjectLike,
+  opts?: Opts<R>,
+): FieldDef<K, R> {
+  const required = opts?.required ? { required: opts.required as R } : {};
+  if (typeof def === "string") {
+    return { kind, object: def, ...required };
+  }
+  return { kind, object: def.name, fields: def.fields, ...required };
+}
+
 export const field = {
   text: <const R extends boolean = false>(opts?: Opts<R>) => base("text", opts),
-  slug: <const R extends boolean = false>(opts?: Opts<R>) => base("slug", opts),
   locale: <const R extends boolean = false>(opts?: Opts<R>) => base("locale", opts),
   image: <const R extends boolean = false>(opts?: Opts<R>) => base("image", opts),
   number: <const R extends boolean = false>(opts?: Opts<R>) => base("number", opts),
@@ -54,14 +74,27 @@ export const field = {
   relation: <To extends string, const R extends boolean = false>(to: To, opts?: Opts<R>) =>
     base("relation", { ...opts, relationTo: to }),
   blocks: <const R extends boolean = false>(opts?: Opts<R>) => base("blocks", opts),
+  object: <const R extends boolean = false>(def: string | ObjectLike, opts?: Opts<R>) =>
+    composite("object", def, opts),
+  array: <const R extends boolean = false>(def: string | ObjectLike, opts?: Opts<R>) =>
+    composite("array", def, opts),
 };
 
 export function serializeField(def: FieldDef): FieldSnapshot {
-  return {
+  const snap: FieldSnapshot = {
     kind: def.kind,
     ...(def.required ? { required: true } : {}),
     ...(def.relationTo ? { relationTo: def.relationTo } : {}),
+    ...(def.object ? { object: def.object } : {}),
   };
+  if (def.fields) {
+    const fields: Record<string, FieldSnapshot> = {};
+    for (const [name, nested] of Object.entries(def.fields)) {
+      fields[name] = serializeField(nested);
+    }
+    snap.fields = fields;
+  }
+  return snap;
 }
 
 export function parseFieldSnapshot(input: unknown): FieldSnapshot {
@@ -72,13 +105,14 @@ export function parseFieldSnapshot(input: unknown): FieldSnapshot {
   const kind = value.kind;
   const allowed: FieldKind[] = [
     "text",
-    "slug",
     "locale",
     "image",
     "relation",
     "number",
     "boolean",
     "blocks",
+    "object",
+    "array",
   ];
   if (typeof kind !== "string" || !allowed.includes(kind as FieldKind)) {
     throw new Error(`invalid field.kind: ${String(kind)}`);
@@ -88,5 +122,15 @@ export function parseFieldSnapshot(input: unknown): FieldSnapshot {
   if (typeof value.relationTo === "string" && value.relationTo.length > 0) {
     snap.relationTo = value.relationTo;
   }
+  if (typeof value.object === "string" && value.object.length > 0) {
+    snap.object = value.object;
+  }
+  if (value.fields && typeof value.fields === "object" && !Array.isArray(value.fields)) {
+    const fields: Record<string, FieldSnapshot> = {};
+    for (const [name, nested] of Object.entries(value.fields as Record<string, unknown>)) {
+      fields[name] = parseFieldSnapshot(nested);
+    }
+    snap.fields = fields;
+  }
   return snap;
 }

package/src/index.ts

@@ -9,6 +9,9 @@ export type {
 } from "./fields";
 export { field, serializeField, parseFieldSnapshot } from "./fields";
 
+export type { ObjectDef, ObjectSnapshot } from "./object";
+export { defineObject, serializeObject, parseObjectSnapshot } from "./object";
+
 export type {
   ModelDef,
   ModelInput,
@@ -21,6 +24,7 @@ export {
   defaultModelPath,
   DEFAULT_MODEL_PATH,
   DEFAULT_PAGE_PATH,
+  IMPLICIT_SINGLETON_SLUG,
   serializeModel,
   serializeSchema,
   parseSchemaSnapshot,
@@ -57,6 +61,7 @@ export type { RouteMatch, RouteModel, MatchRouteOptions } from "./routes";
 export {
   DEFAULT_ROUTE,
   compileRoutePattern,
+  isRoutable,
   matchRoute,
   normalizePathname,
   routeFor,
@@ -73,6 +78,9 @@ export {
   repoPathFromModel,
   contentExtFromPath,
   contentExtForType,
+  EMPTY_LOCALE_SEGMENT,
+  encodeDocLocale,
+  decodeDocLocale,
   encodeGitBranch,
   decodeGitBranch,
   s3HeadKey,

package/src/model.ts

@@ -8,6 +8,7 @@ import {
 } from "./fields";
 import { parseBlockSnapshot, serializeBlock, type BlockDef, type BlockSnapshot } from "./block";
 import type { BlockInstance } from "./block";
+import { parseObjectSnapshot, serializeObject, type ObjectDef, type ObjectSnapshot } from "./object";
 import type { DocFormat } from "./doc-format";
 
 export type ModelDef = {
@@ -17,8 +18,14 @@ export type ModelDef = {
   /**
    * URL template for the host catch-all route, e.g. "/blog/{slug}".
    * Defaults to "/{locale}/{type}/{slug}" when omitted (see routes.ts).
+   * `false` excludes the model from the catch-all. Singletons default to `false`.
    */
-  route?: string;
+  route?: string | false;
+  /**
+   * At most one document for each identity the path allows (one file, or one
+   * file per `{locale}` when that placeholder is present).
+   */
+  singleton?: boolean;
   /** File format. Default `"mdx"`. `"page"` stores JSON with a blocks array. */
   format?: DocFormat;
   /**
@@ -44,16 +51,41 @@ export function defaultModelPath(type: string, format: DocFormat = "mdx"): strin
 export type ModelSnapshot = {
   type: string;
   path: string;
-  route?: string;
+  route?: string | false;
+  singleton?: boolean;
   format?: DocFormat;
   indexSlug?: string;
   fields: Record<string, FieldSnapshot>;
 };
 
+/** Implicit file stem when a singleton path omits `{slug}`. */
+export const IMPLICIT_SINGLETON_SLUG = "index";
+
+export function assertModelPath(path: string, singleton: boolean, label = "model.path"): void {
+  if (!singleton && !path.includes("{slug}")) {
+    throw new Error(`${label} must include {slug}`);
+  }
+}
+
+export function assertModelRoute(
+  route: string | false,
+  singleton: boolean,
+  label = "model.route",
+): void {
+  if (route === false) return;
+  if (typeof route !== "string" || !route.startsWith("/")) {
+    throw new Error(`${label} must start with "/"`);
+  }
+  if (!singleton && !route.includes("{slug}")) {
+    throw new Error(`${label} must include {slug}`);
+  }
+}
+
 export type SchemaSnapshot = {
   version: number;
   models: ModelSnapshot[];
   blocks?: BlockSnapshot[];
+  objects?: ObjectSnapshot[];
 };
 
 type WithPath<D extends ModelInput> = D extends { path: string } ? D : D & { path: string };
@@ -69,20 +101,17 @@ export function defineModel<const D extends ModelInput>(def: D): WithPath<D> {
   if (def.format !== undefined && def.format !== "mdx" && def.format !== "page") {
     throw new Error('model.format must be "mdx" or "page"');
   }
+  const singleton = def.singleton === true;
+  if (singleton && def.indexSlug !== undefined) {
+    throw new Error("model.singleton cannot be combined with indexSlug");
+  }
   const path = def.path ?? defaultModelPath(def.type, def.format ?? "mdx");
   if (typeof path !== "string" || !path) {
     throw new Error("model.path must be a non-empty string");
   }
-  if (!path.includes("{locale}") || !path.includes("{slug}")) {
-    throw new Error("model.path must include {locale} and {slug}");
-  }
+  assertModelPath(path, singleton);
   if (def.route !== undefined) {
-    if (typeof def.route !== "string" || !def.route.startsWith("/")) {
-      throw new Error('model.route must start with "/"');
-    }
-    if (!def.route.includes("{slug}")) {
-      throw new Error("model.route must include {slug}");
-    }
+    assertModelRoute(def.route, singleton);
   }
   if (def.indexSlug !== undefined) {
     if (typeof def.indexSlug !== "string" || !def.indexSlug.trim()) {
@@ -92,7 +121,11 @@ export function defineModel<const D extends ModelInput>(def: D): WithPath<D> {
   if (!def.fields || typeof def.fields !== "object") {
     throw new Error("model.fields is required");
   }
-  return (def.path === undefined ? { ...def, path } : def) as WithPath<D>;
+  const withPath = (def.path === undefined ? { ...def, path } : { ...def }) as WithPath<D>;
+  if (singleton && def.route === undefined) {
+    return { ...withPath, route: false };
+  }
+  return withPath;
 }
 
 type Simplify<T> = { -readonly [K in keyof T]: T[K] } & {};
@@ -135,6 +168,7 @@ export function serializeModel(model: ModelDef): ModelSnapshot {
     fields,
   };
   if (model.route !== undefined) snapshot.route = model.route;
+  if (model.singleton) snapshot.singleton = true;
   if (model.format === "page") snapshot.format = "page";
   if (model.indexSlug !== undefined) snapshot.indexSlug = model.indexSlug.trim();
   return snapshot;
@@ -143,6 +177,7 @@ export function serializeModel(model: ModelDef): ModelSnapshot {
 export function serializeSchema(
   models: ModelDef[],
   blocks?: BlockDef[],
+  objects?: ObjectDef[],
 ): SchemaSnapshot {
   const snapshot: SchemaSnapshot = {
     version: 1,
@@ -151,6 +186,9 @@ export function serializeSchema(
   if (blocks && blocks.length > 0) {
     snapshot.blocks = blocks.map(serializeBlock);
   }
+  if (objects && objects.length > 0) {
+    snapshot.objects = objects.map(serializeObject);
+  }
   return snapshot;
 }
 
@@ -177,13 +215,21 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
     if (typeof m.path !== "string" || !m.path) {
       throw new Error(`schema.models[${i}].path is required`);
     }
-    if (!m.path.includes("{locale}") || !m.path.includes("{slug}")) {
-      throw new Error(
-        `schema.models[${i}].path must include {locale} and {slug}`,
-      );
+    const singleton = m.singleton === true;
+    try {
+      assertModelPath(m.path, singleton, `schema.models[${i}].path`);
+    } catch (err) {
+      throw err instanceof Error ? err : new Error(String(err));
+    }
+    if (m.route !== undefined) {
+      try {
+        assertModelRoute(m.route as string | false, singleton, `schema.models[${i}].route`);
+      } catch (err) {
+        throw err instanceof Error ? err : new Error(String(err));
+      }
     }
-    if (m.route !== undefined && (typeof m.route !== "string" || !m.route.startsWith("/"))) {
-      throw new Error(`schema.models[${i}].route must be a string starting with "/"`);
+    if (singleton && m.indexSlug !== undefined) {
+      throw new Error(`schema.models[${i}]: singleton cannot be combined with indexSlug`);
     }
     if (!m.fields || typeof m.fields !== "object" || Array.isArray(m.fields)) {
       throw new Error(`schema.models[${i}].fields must be an object`);
@@ -194,13 +240,14 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
     )) {
       try {
         fields[name] = parseFieldSnapshot(fieldRaw);
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : "invalid field";
-        throw new Error(`schema.models[${i}].fields.${name}: ${msg}`);
+      } catch {
+        // Drop unknown kinds (e.g. leftover slug) so a stored snapshot still loads.
       }
     }
     const snapshot: ModelSnapshot = { type: m.type, path: m.path, fields };
-    if (typeof m.route === "string") snapshot.route = m.route;
+    if (m.route === false || (singleton && m.route === undefined)) snapshot.route = false;
+    else if (typeof m.route === "string") snapshot.route = m.route;
+    if (singleton) snapshot.singleton = true;
     if (m.format === "page") snapshot.format = "page";
     else if (m.format !== undefined && m.format !== "mdx") {
       throw new Error(`schema.models[${i}].format must be "mdx" or "page"`);
@@ -254,5 +301,27 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
     }
   }
 
-  return { version, models, blocks };
+  let objects: ObjectSnapshot[] = [];
+  if (value.objects !== undefined) {
+    if (!Array.isArray(value.objects)) {
+      throw new Error("schema.objects must be an array");
+    }
+    objects = value.objects.map((raw, i) => {
+      try {
+        return parseObjectSnapshot(raw);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "invalid object";
+        throw new Error(`schema.objects[${i}]: ${msg}`);
+      }
+    });
+    const objectNames = new Set<string>();
+    for (const object of objects) {
+      if (objectNames.has(object.name)) {
+        throw new Error(`duplicate object name: ${object.name}`);
+      }
+      objectNames.add(object.name);
+    }
+  }
+
+  return { version, models, blocks, objects };
 }

package/src/node/create-backmatter.ts

@@ -1,6 +1,7 @@
 // packages/core/src/node/create-backmatter.ts
 import type { ModelDef, ModelSnapshot } from "../model";
 import type { BlockDef } from "../block";
+import type { ObjectDef } from "../object";
 import { getDocFromApi, listDocsFromApi } from "../api-loader";
 import { getDocFromFs, listDocsFromFs } from "./fs-loader";
 import { createQuery, type DocLoader, type Query } from "../query";
@@ -17,6 +18,7 @@ export type CreateBackmatterOptions<Models extends readonly ModelDef[] = readonl
   BackmatterConfig & {
     models: Models;
     blocks?: readonly BlockDef[];
+    objects?: readonly ObjectDef[];
     /**
      * When true, API fetches use Next cache tags instead of `cache: "no-store"`.
      * `@backmatter/next` turns this on.
@@ -55,6 +57,7 @@ function toSnapshots(models: readonly ModelDef[]): ModelSnapshot[] {
       fields: m.fields as ModelSnapshot["fields"],
     };
     if (m.route !== undefined) snapshot.route = m.route;
+    if (m.singleton) snapshot.singleton = true;
     if (m.format === "page") snapshot.format = "page";
     if (m.indexSlug !== undefined) snapshot.indexSlug = m.indexSlug;
     return snapshot;
@@ -64,7 +67,7 @@ function toSnapshots(models: readonly ModelDef[]): ModelSnapshot[] {
 export function createBackmatter<const Models extends readonly ModelDef[]>(
   options: CreateBackmatterOptions<Models>,
 ): BackmatterClient<Models> {
-  const { models: modelDefs, blocks: blockDefs, taggedApiFetch, sync = true, ...rest } = options;
+  const { models: modelDefs, blocks: blockDefs, objects: objectDefs, taggedApiFetch, sync = true, ...rest } = options;
   const config = resolveConfig(rest);
   const models = toSnapshots(modelDefs);
   const siteRoot = config.siteRoot ?? process.cwd();
@@ -88,6 +91,7 @@ export function createBackmatter<const Models extends readonly ModelDef[]>(
         hostToken,
         models: [...modelDefs],
         blocks: blockDefs ? [...blockDefs] : undefined,
+        objects: objectDefs ? [...objectDefs] : undefined,
         branch: config.branch,
         siteUrl,
       }).catch((err) => {

package/src/node/discover.ts

@@ -7,6 +7,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { ModelDef } from "../model";
+import type { ObjectDef } from "../object";
 
 export type ModelFile = {
   /** Absolute path. */
@@ -96,6 +97,10 @@ export function listBlockFallbackFiles(
 export function listLayoutFiles(root: string, layoutsDir = "layouts"): ModelFile[] {
   return listModelFiles(root, layoutsDir);
 }
+
+export function listObjectFiles(root: string, objectsDir = "objects"): ModelFile[] {
+  return listModelFiles(root, objectsDir);
+}
 export function listBlockFiles(
   root: string,
   blocksDir = "blocks",
@@ -189,3 +194,40 @@ export async function discoverBlocks(
   }
   return blocks;
 }
+
+function isObjectDef(value: unknown): value is ObjectDef {
+  if (!value || typeof value !== "object") return false;
+  const m = value as Record<string, unknown>;
+  return typeof m.name === "string" && typeof m.fields === "object" && !("component" in m) && !("type" in m);
+}
+
+/**
+ * Import every object file. The file stem must equal `object.name`.
+ */
+export async function discoverObjects(
+  root: string,
+  objectsDir = "objects",
+): Promise<ObjectDef[]> {
+  const objects: ObjectDef[] = [];
+  const names = new Set<string>();
+  for (const { file, stem } of listObjectFiles(root, objectsDir)) {
+    const rel = path.relative(root, file);
+    const mod = (await import(
+      /* webpackIgnore: true */ /* turbopackIgnore: true */ pathToFileURL(file).href
+    )) as { default?: unknown };
+    if (!isObjectDef(mod.default)) {
+      throw new Error(`${rel} must \`export default defineObject({ ... })\``);
+    }
+    if (mod.default.name !== stem) {
+      throw new Error(
+        `${rel} defines name "${mod.default.name}" but the file is named "${stem}"; rename one so they match`,
+      );
+    }
+    if (names.has(mod.default.name)) {
+      throw new Error(`duplicate object name "${mod.default.name}" (${rel})`);
+    }
+    names.add(mod.default.name);
+    objects.push(mod.default);
+  }
+  return objects;
+}

package/src/node/fs-loader.ts

@@ -63,7 +63,7 @@ export async function listDocsFromFs(
       }
     }
     docs.push({
-      locale: hit.locale,
+      locale: hit.locale ?? "",
       type: hit.type,
       slug: hit.slug,
       frontmatter,

package/src/node/generate.ts

@@ -11,6 +11,7 @@ import {
   listLayoutFiles,
   listMdxFiles,
   listModelFiles,
+  listObjectFiles,
   type BlockFile,
   type ModelFile,
 } from "./discover";
@@ -32,6 +33,7 @@ export type GenerateOptions = {
   blocksDir?: string;
   mdxDir?: string;
   layoutsDir?: string;
+  objectsDir?: string;
   /** Module that exports `createBackmatter`. Auto-detected from package.json when omitted. */
   sdk?: string;
   /** Write to disk. Default: true. `false` only renders (used by the bundler loader). */
@@ -59,6 +61,7 @@ export type GenerateResult = {
   blocks: BlockFile[];
   mdx: BlockFile[];
   layouts: ModelFile[];
+  objects: ModelFile[];
   skippedBlocks: string[];
   skippedMdx: string[];
   /** Absolute path of `backmatter.config.*` when present. */
@@ -158,9 +161,11 @@ export function renderSyncBarrel(input: {
   outDir: string;
   models: ModelFile[];
   blocks: BlockFile[];
+  objects?: ModelFile[];
   configFile: string | null;
   sdk: string;
 }): string {
+  const objects = input.objects ?? [];
   const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
   if (input.configFile) {
     lines.push(`import config from "${importSpecifier(input.outDir, input.configFile)}";`);
@@ -173,14 +178,19 @@ export function renderSyncBarrel(input: {
   for (const b of input.blocks) {
     lines.push(`import ${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
   }
+  for (const object of objects) {
+    lines.push(`import ${object.importName} from "${importSpecifier(input.outDir, object.file)}";`);
+  }
   lines.push("");
   lines.push(`export const models = [${input.models.map((m) => m.importName).join(", ")}] as const;`);
   lines.push("export type Models = typeof models;");
   lines.push("");
   lines.push(`export const blocks = [${input.blocks.map((b) => b.name).join(", ")}] as const;`);
   lines.push("");
+  lines.push(`export const objects = [${objects.map((o) => o.importName).join(", ")}] as const;`);
+  lines.push("");
   lines.push("/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */");
-  lines.push("export const cms = createBackmatter({ ...config, models, blocks, sync: true });");
+  lines.push("export const cms = createBackmatter({ ...config, models, blocks, objects, sync: true });");
   return `${lines.join("\n")}\n`;
 }
 
@@ -265,6 +275,7 @@ export function generate(options: GenerateOptions): GenerateResult {
     options.mdxDir ?? DEFAULT_DIRS.mdx,
   );
   const layouts = listLayoutFiles(root, options.layoutsDir ?? DEFAULT_DIRS.layouts);
+  const objects = listObjectFiles(root, options.objectsDir ?? DEFAULT_DIRS.objects);
   const sdk = options.sdk ?? detectSdk(root);
   const configFile = findConfigFile(root);
   const write = options.write ?? true;
@@ -275,7 +286,7 @@ export function generate(options: GenerateOptions): GenerateResult {
     "block-fallbacks.ts": renderBlockFallbacksBarrel({ outDir, fallbacks }),
     "mdx.ts": renderMdxBarrel({ outDir, mdx }),
     "layouts.ts": renderLayoutsBarrel({ outDir, layouts }),
-    "sync.ts": renderSyncBarrel({ outDir, models, blocks, configFile, sdk }),
+    "sync.ts": renderSyncBarrel({ outDir, models, blocks, objects, configFile, sdk }),
   };
   const outputs: GeneratedFile[] = REGISTRY_FILES.map((name) => {
     const file = path.join(outDir, name);
@@ -295,6 +306,7 @@ export function generate(options: GenerateOptions): GenerateResult {
     blocks,
     mdx,
     layouts,
+    objects,
     skippedBlocks,
     skippedMdx,
     configFile,

package/src/node/index.ts

@@ -8,11 +8,13 @@ export { getDocFromFs, listDocsFromFs, walkMdxFiles, walkContentFiles } from "./
 export {
   discoverModels,
   discoverBlocks,
+  discoverObjects,
   listBlockFallbackFiles,
   listBlockFiles,
   listLayoutFiles,
   listMdxFiles,
   listModelFiles,
+  listObjectFiles,
   toIdentifier,
 } from "./discover";
 export type { BlockFile, ModelFile } from "./discover";

package/src/object.ts

@@ -0,0 +1,58 @@
+// packages/core/src/object.ts
+import {
+  type FieldDef,
+  type FieldSnapshot,
+  parseFieldSnapshot,
+  serializeField,
+} from "./fields";
+
+export type ObjectDef = {
+  name: string;
+  fields: Record<string, FieldDef>;
+};
+
+export type ObjectSnapshot = {
+  name: string;
+  fields: Record<string, FieldSnapshot>;
+};
+
+const NAME = /^[A-Za-z][A-Za-z0-9]*$/;
+
+export function defineObject<const D extends ObjectDef>(def: D): D {
+  if (!def.name || typeof def.name !== "string") {
+    throw new Error("object.name is required");
+  }
+  if (!NAME.test(def.name)) {
+    throw new Error('object.name must be an identifier (e.g. "link")');
+  }
+  if (!def.fields || typeof def.fields !== "object") {
+    throw new Error("object.fields is required");
+  }
+  return def;
+}
+
+export function serializeObject(object: ObjectDef): ObjectSnapshot {
+  const fields: Record<string, FieldSnapshot> = {};
+  for (const [name, def] of Object.entries(object.fields)) {
+    fields[name] = serializeField(def);
+  }
+  return { name: object.name, fields };
+}
+
+export function parseObjectSnapshot(input: unknown): ObjectSnapshot {
+  if (!input || typeof input !== "object") {
+    throw new Error("object must be an object");
+  }
+  const value = input as Record<string, unknown>;
+  if (typeof value.name !== "string" || !value.name) {
+    throw new Error("object.name is required");
+  }
+  if (!value.fields || typeof value.fields !== "object" || Array.isArray(value.fields)) {
+    throw new Error("object.fields must be an object");
+  }
+  const fields: Record<string, FieldSnapshot> = {};
+  for (const [name, fieldRaw] of Object.entries(value.fields as Record<string, unknown>)) {
+    fields[name] = parseFieldSnapshot(fieldRaw);
+  }
+  return { name: value.name, fields };
+}

package/src/path.ts

@@ -1,8 +1,8 @@
 // packages/core/src/path.ts
-import type { ModelSnapshot } from "./model";
+import { IMPLICIT_SINGLETON_SLUG, type ModelSnapshot } from "./model";
 
 export type PathMatch = {
-  locale: string;
+  locale?: string;
   slug: string;
   type: string;
 };
@@ -31,16 +31,22 @@ export function matchModelPath(
   const normalized = repoPath.replace(/^\/+/, "");
   const re = compilePathPattern(model.path);
   const m = re.exec(normalized);
-  if (!m?.groups?.locale || !m.groups.slug) return null;
+  if (!m) return null;
+  const hasLocale = model.path.includes("{locale}");
+  const hasSlug = model.path.includes("{slug}");
+  if (hasLocale && !m.groups?.locale) return null;
+  if (hasSlug && !m.groups?.slug) return null;
   // Strip trailing extension from slug if the template baked it into the capture.
-  let slug = m.groups.slug;
+  let slug = hasSlug ? m.groups!.slug! : IMPLICIT_SINGLETON_SLUG;
   const ext = contentExtFromPath(model.path);
   const suffix = `.${ext}`;
-  if (model.path.endsWith(suffix) && slug.endsWith(suffix)) {
+  if (hasSlug && model.path.endsWith(suffix) && slug.endsWith(suffix)) {
     slug = slug.slice(0, -suffix.length);
   }
   if (!slug) return null;
-  return { locale: m.groups.locale, slug, type: model.type };
+  const match: PathMatch = { slug, type: model.type };
+  if (hasLocale) match.locale = m.groups!.locale;
+  return match;
 }
 
 export function matchAnyModelPath(
@@ -69,12 +75,12 @@ export function contentExtForType(
 
 export function repoPathFromModel(
   model: Pick<ModelSnapshot, "path">,
-  locale: string,
+  locale: string | undefined,
   slug: string,
 ): string {
-  return model.path
-    .replaceAll("{locale}", locale)
-    .replaceAll("{slug}", slug);
+  let out = model.path;
+  if (locale !== undefined) out = out.replaceAll("{locale}", locale);
+  return out.replaceAll("{slug}", slug);
 }
 
 // ---------------------------------------------------------------------------
@@ -115,38 +121,55 @@ export function s3TreePrefix(
   return `${branchRoot(workspaceId, branch)}/trees/${encodeURIComponent(userId)}/`;
 }
 
+/** URL stand-in when a model path has no `{locale}` — not a language code. */
+export const EMPTY_LOCALE_SEGMENT = "-";
+
+export function encodeDocLocale(locale: string | undefined): string {
+  return locale ? locale : EMPTY_LOCALE_SEGMENT;
+}
+
+export function decodeDocLocale(segment: string): string {
+  return segment === EMPTY_LOCALE_SEGMENT ? "" : segment;
+}
+
+function contentLeaf(type: string, slug: string, ext: string, locale?: string): string {
+  const leaf = `${type}/${slug}.${ext}`;
+  return locale ? `${locale}/${leaf}` : leaf;
+}
+
 export function s3HeadKey(
   workspaceId: string,
   branch: string,
-  locale: string,
+  locale: string | undefined,
   type: string,
   slug: string,
   ext = "mdx",
 ): string {
-  return `${s3HeadPrefix(workspaceId, branch)}${locale}/${type}/${slug}.${ext}`;
+  return `${s3HeadPrefix(workspaceId, branch)}${contentLeaf(type, slug, ext, locale || undefined)}`;
 }
 
 export function s3TreeKey(
   workspaceId: string,
   branch: string,
   userId: string,
-  locale: string,
+  locale: string | undefined,
   type: string,
   slug: string,
   ext = "mdx",
 ): string {
-  return `${s3TreePrefix(workspaceId, branch, userId)}${locale}/${type}/${slug}.${ext}`;
+  return `${s3TreePrefix(workspaceId, branch, userId)}${contentLeaf(type, slug, ext, locale || undefined)}`;
 }
 
 /** HEAD blob sha for conflict checks. */
 export function s3ShaMetaKey(
   workspaceId: string,
   branch: string,
-  locale: string,
+  locale: string | undefined,
   type: string,
   slug: string,
 ): string {
-  return `${branchRoot(workspaceId, branch)}/meta/shas/${locale}/${type}/${slug}.json`;
+  const leaf = locale ? `${locale}/${type}/${slug}.json` : `${type}/${slug}.json`;
+  return `${branchRoot(workspaceId, branch)}/meta/shas/${leaf}`;
 }
 
 export type ParsedContentKey = {
@@ -154,7 +177,7 @@ export type ParsedContentKey = {
   source: ContentSource;
   /** Owner of the working tree; null for head keys. */
   userId: string | null;
-  locale: string;
+  locale?: string;
   type: string;
   slug: string;
 };
@@ -168,29 +191,41 @@ export function parseS3ContentKey(
   if (!key.startsWith(prefix)) return null;
   const rest = key.slice(prefix.length);
 
-  const head = /^([^/]+)\/head\/([^/]+)\/([^/]+)\/(.+)\.(mdx|json)$/.exec(rest);
+  const head = /^([^/]+)\/head\/(.+)\.(mdx|json)$/.exec(rest);
   if (head) {
-    return {
-      branch: decodeGitBranch(head[1]!),
-      source: "head",
-      userId: null,
-      locale: head[2]!,
-      type: head[3]!,
-      slug: head[4]!,
-    };
+    const parsed = parseContentLeaf(head[2]!);
+    if (parsed) {
+      return {
+        branch: decodeGitBranch(head[1]!),
+        source: "head",
+        userId: null,
+        ...parsed,
+      };
+    }
   }
 
-  const tree =
-    /^([^/]+)\/trees\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)\.(mdx|json)$/.exec(rest);
+  const tree = /^([^/]+)\/trees\/([^/]+)\/(.+)\.(mdx|json)$/.exec(rest);
   if (tree) {
-    return {
-      branch: decodeGitBranch(tree[1]!),
-      source: "tree",
-      userId: decodeURIComponent(tree[2]!),
-      locale: tree[3]!,
-      type: tree[4]!,
-      slug: tree[5]!,
-    };
+    const parsed = parseContentLeaf(tree[3]!);
+    if (parsed) {
+      return {
+        branch: decodeGitBranch(tree[1]!),
+        source: "tree",
+        userId: decodeURIComponent(tree[2]!),
+        ...parsed,
+      };
+    }
+  }
+  return null;
+}
+
+function parseContentLeaf(leaf: string): { locale?: string; type: string; slug: string } | null {
+  const parts = leaf.split("/");
+  if (parts.length === 3) {
+    return { locale: parts[0], type: parts[1]!, slug: parts[2]! };
+  }
+  if (parts.length === 2) {
+    return { type: parts[0]!, slug: parts[1]! };
   }
   return null;
 }

package/src/query.ts

@@ -1,7 +1,7 @@
 // packages/core/src/query.ts
 import type { BackmatterDoc, BackmatterDocSummary } from "./doc";
 import type { FieldKind } from "./fields";
-import type { InferFrontmatter, ModelDef } from "./model";
+import { IMPLICIT_SINGLETON_SLUG, type InferFrontmatter, type ModelDef } from "./model";
 import { normalizeFrontmatter } from "./zod";
 
 /** Loader the query layer sits on: the FS or API loaders behind createBackmatter. */
@@ -19,7 +19,7 @@ type KeysOfKind<M extends ModelDef, K extends FieldKind> = {
   [N in keyof M["fields"]]: M["fields"][N]["kind"] extends K ? N : never;
 }[keyof M["fields"]];
 
-type ScalarKind = "text" | "slug" | "locale" | "number" | "boolean";
+type ScalarKind = "text" | "locale" | "number" | "boolean";
 
 /** Equality filters on slug and scalar frontmatter fields. */
 export type Where<M extends ModelDef> = Partial<
@@ -50,8 +50,20 @@ export type Resolved<
     : never;
 };
 
+type PathHasLocale<M extends ModelDef> = M["path"] extends `${string}{locale}${string}`
+  ? true
+  : false;
+
+type ModelGet<M extends ModelDef> = M["singleton"] extends true
+  ? PathHasLocale<M> extends true
+    ? (locale: string) => Promise<TypedDoc<M> | null>
+    : () => Promise<TypedDoc<M> | null>
+  : PathHasLocale<M> extends true
+    ? (locale: string, slug: string) => Promise<TypedDoc<M> | null>
+    : (slug: string) => Promise<TypedDoc<M> | null>;
+
 export type ModelQuery<M extends ModelDef, Models extends readonly ModelDef[]> = {
-  get(locale: string, slug: string): Promise<TypedDoc<M> | null>;
+  get: ModelGet<M>;
   findMany<I extends Include<M> = {}>(opts?: {
     locale?: string;
     where?: Where<M>;
@@ -75,6 +87,22 @@ export function createQuery<const Models extends readonly ModelDef[]>(
 ): Query<Models> {
   const byType = new Map<string, ModelDef>(models.map((m) => [m.type, m]));
 
+  function identityFor(type: string, a?: string, b?: string): { locale: string; slug: string } {
+    const model = byType.get(type);
+    const localized = model?.path.includes("{locale}") ?? true;
+    const singleton = model?.singleton === true;
+    if (singleton) {
+      return {
+        locale: localized ? (a ?? "") : "",
+        slug: model?.path.includes("{slug}") ? (localized ? (b ?? IMPLICIT_SINGLETON_SLUG) : (a ?? IMPLICIT_SINGLETON_SLUG)) : IMPLICIT_SINGLETON_SLUG,
+      };
+    }
+    return {
+      locale: localized ? (a ?? "") : "",
+      slug: localized ? (b ?? "") : (a ?? ""),
+    };
+  }
+
   async function get(type: string, locale: string, slug: string): Promise<BackmatterDoc | null> {
     const doc = await loader.getDoc(locale, type, slug);
     if (!doc) return null;
@@ -157,7 +185,10 @@ export function createQuery<const Models extends readonly ModelDef[]>(
   const query: Record<string, unknown> = {};
   for (const m of models) {
     query[m.type] = {
-      get: (locale: string, slug: string) => get(m.type, locale, slug),
+      get: (a?: string, b?: string) => {
+        const id = identityFor(m.type, a, b);
+        return get(m.type, id.locale, id.slug);
+      },
       findMany: (opts?: RawOpts) => findMany(m.type, opts),
     };
   }

package/src/routes.ts

@@ -6,6 +6,10 @@ export const DEFAULT_ROUTE = "/{locale}/{type}/{slug}";
 
 export type RouteModel = Pick<ModelSnapshot, "type" | "route" | "indexSlug">;
 
+export function isRoutable(model: Pick<RouteModel, "route">): boolean {
+  return model.route !== false;
+}
+
 export type RouteMatch = {
   type: string;
   locale: string;
@@ -21,11 +25,13 @@ export type MatchRouteOptions = {
 
 /** The model's route template with `{type}` already substituted. */
 export function routeTemplate(model: RouteModel): string {
+  if (model.route === false) return "";
   return (model.route ?? DEFAULT_ROUTE).replaceAll("{type}", model.type);
 }
 
 /** Build the public URL path for a document, e.g. "/en/blog/hello". */
 export function routeFor(model: RouteModel, locale: string, slug: string): string {
+  if (model.route === false) return "";
   if (model.indexSlug && slug === model.indexSlug) return "/";
   return routeTemplate(model)
     .replaceAll("{locale}", encodeURIComponent(locale))
@@ -87,13 +93,13 @@ export function matchRoute(
 ): RouteMatch | null {
   const target = normalizePathname(pathname);
   if (target === "/") {
-    const index = models.find((model) => model.indexSlug);
+    const index = models.find((model) => model.indexSlug && isRoutable(model));
     if (index?.indexSlug) {
       return { type: index.type, locale: options.defaultLocale, slug: index.indexSlug };
     }
     return null;
   }
-  for (const model of sortByRouteSpecificity(models)) {
+  for (const model of sortByRouteSpecificity(models.filter(isRoutable))) {
     const template = routeTemplate(model);
     const m = compileRoutePattern(template).exec(target);
     if (!m?.groups?.slug) continue;

package/src/sync-schema.ts

@@ -5,6 +5,7 @@ import {
   type ModelSnapshot,
 } from "./model";
 import type { BlockDef } from "./block";
+import type { ObjectDef } from "./object";
 
 export function detectGitBranch(
   env: Record<string, string | undefined> = process.env,
@@ -22,13 +23,18 @@ export type SyncSchemaOptions = {
   hostToken: string;
   models: Array<ModelDef | ModelSnapshot>;
   blocks?: BlockDef[];
+  objects?: ObjectDef[];
   branch?: string;
   siteUrl?: string;
 };
 
 export async function syncSchema(options: SyncSchemaOptions): Promise<void> {
   const branch = options.branch ?? detectGitBranch() ?? "main";
-  const payload = serializeSchema(options.models as ModelDef[], options.blocks);
+  const payload = serializeSchema(
+    options.models as ModelDef[],
+    options.blocks,
+    options.objects,
+  );
   const body: { payload: ReturnType<typeof serializeSchema>; branch: string; siteUrl?: string } = {
     payload,
     branch,

package/src/zod.ts

@@ -5,16 +5,20 @@ import type { Frontmatter } from "./mdx";
 import type { ModelSnapshot } from "./model";
 
 /** Primitive a field kind is stored as in frontmatter; used in error messages. */
-export function expectedTypeFor(kind: FieldKind): "string" | "number" | "boolean" | "array" {
+export function expectedTypeFor(
+  kind: FieldKind,
+): "string" | "number" | "boolean" | "array" | "object" {
   switch (kind) {
     case "number":
       return "number";
     case "boolean":
       return "boolean";
     case "blocks":
+    case "array":
       return "array";
+    case "object":
+      return "object";
     case "text":
-    case "slug":
     case "locale":
     case "image":
     case "relation":
@@ -34,11 +38,12 @@ export function exampleValueFor(kind: FieldKind): unknown {
     case "boolean":
       return false;
     case "blocks":
+    case "array":
       return [];
+    case "object":
+      return {};
     case "image":
       return "https://example.com/image.jpg";
-    case "slug":
-      return "example-slug";
     case "locale":
       return "en";
     case "relation":
@@ -52,6 +57,15 @@ export function exampleValueFor(kind: FieldKind): unknown {
   }
 }
 
+function objectZod(field: FieldSnapshot): z.ZodType {
+  if (!field.fields) return z.record(z.string(), z.unknown());
+  const shape: Record<string, z.ZodType> = {};
+  for (const [name, nested] of Object.entries(field.fields)) {
+    shape[name] = fieldZod(nested);
+  }
+  return z.looseObject(shape);
+}
+
 function fieldZod(field: FieldSnapshot): z.ZodType {
   if (field.kind === "blocks") {
     const item = z.object({
@@ -62,6 +76,14 @@ function fieldZod(field: FieldSnapshot): z.ZodType {
     const arr = field.required ? z.array(item).min(1) : z.array(item).optional();
     return arr;
   }
+  if (field.kind === "object") {
+    const obj = objectZod(field);
+    return field.required ? obj : obj.optional();
+  }
+  if (field.kind === "array") {
+    const arr = z.array(objectZod(field));
+    return field.required ? arr : arr.optional();
+  }
   let base: z.ZodType;
   switch (expectedTypeFor(field.kind)) {
     case "number":