@pitlane/content 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @pitlane/content
+
+## 0.1.0
+
+Initial release.
+
+- `createContent` returns typed collection handles synchronously without loading
+  entries. Reads and rendering remain asynchronous; declaration errors throw
+  synchronously.
+- `getCollection`, `getCollection(filter)`, and `getEntry` over entries sorted
+  by id; `c.reference(collection)` for typed pointers between collections.
+- `render()` resolves an entry's Markdown or MDX to a Remix component and its
+  heading list, parsing nothing until it is called.
+- Two loader interfaces: `ContentLoader` resolves a whole collection in one
+  execution and can be prebuilt, `LiveLoader` answers one query at a time and
+  runs on every read. `loaders.glob` and `loaders.file` implement the first.
+- `contentLayer()` from `@pitlane/content/vite` loads `ContentLoader` collections
+  after evaluating their declarations and inlines them into the bundle. It waits
+  for loading and validation before emitting, and watches the loaders' sources
+  in dev.
+- `headings()` from `@pitlane/content/satteri` produces the heading list on both
+  rendering paths.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Malstrom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @pitlane/content
+
+Schema-validated, cross-referenced content collections for [Remix 3](https://remix.run).
+
+Reads Markdown, MDX, JSON, and YAML into collections a controller queries like a
+database. Frontmatter is validated against a schema, one entry can reference
+another, and the types come from the schema rather than from generated code.
+
+```sh
+npm install @pitlane/content
+```
+
+```ts
+import { createContent } from "@pitlane/content";
+import * as loaders from "@pitlane/content/loaders";
+import * as s from "remix/data-schema";
+import * as coerce from "remix/data-schema/coerce";
+
+export let content = createContent(c => ({
+    blog: c.collection({
+        loader: loaders.glob({ pattern: "**/*.mdx", base: "app/content/blog" }),
+        schema: s.object({
+            title: s.string(),
+            publishedOn: coerce.date(),
+            author: c.reference("authors"),
+        }),
+    }),
+    authors: c.collection({
+        loader: loaders.file("app/content/authors.json"),
+        schema: s.object({ name: s.string() }),
+    }),
+}));
+```
+
+```ts
+let posts = await content.blog.getCollection();
+let post = await content.blog.getEntry(params.slug);
+let { Content, headings } = await post.render();
+let author = await content.authors.getEntry(post.data.author);
+```
+
+`createContent()` returns synchronously without loading entries. Import the
+returned object wherever you need it; reads and rendering stay asynchronous.
+
+The loaders are ordinary runtime code, which covers Node, Bun, Deno, and
+container hosts. For a host with no filesystem, add `contentLayer()` from
+`@pitlane/content/vite` and the build resolves the collections ahead of time,
+inlining entry data and compiling Markdown bodies into the bundle. The
+collection declarations do not change.
+
+## Entry points
+
+| Entry point                | Exports                                     |
+| -------------------------- | ------------------------------------------- |
+| `@pitlane/content`         | `createContent` and the collection types    |
+| `@pitlane/content/loaders` | `glob`, `file`                              |
+| `@pitlane/content/satteri` | `headings` and `rawStyles`, Sätteri plugins |
+| `@pitlane/content/vite`    | `contentLayer`, the build-time plugin       |
+
+## Without Remix
+
+Every peer dependency is optional. The data path, meaning the loaders, schema
+validation, and both query methods, has no static dependency on `remix` and
+works with any [Standard Schema](https://standardschema.dev) validator. Only
+`render()` needs Remix, because it resolves to a Remix component, and it says
+so if you call it without one.
+
+## Documentation
+
+- [Content](https://pitlane.tools/guides/content), whose toggle also serves
+  [an application that runs without a build](https://pitlane.tools/guides/content-no-build)
+- [Creating a content loader](https://pitlane.tools/guides/content-loaders)
+- [API reference](https://pitlane.tools/package/content/)
+
+## License
+
+MIT

package/dist/codegen.d.mts

@@ -0,0 +1,40 @@
+import { p as LoadedEntry } from "./types-xSR1WTBq.mjs";
+//#region src/codegen.d.ts
+/** The prefix of the virtual modules that carry each entry's raw body. */
+declare const BODY_PREFIX = "\0pitlane-content/entry/";
+/** One entry's raw body, and the file it was read from. */
+interface Body {
+  source: string;
+  format: "md" | "mdx";
+  /** Absent for a loader that produced the body without a file. */
+  filePath?: string;
+}
+/**
+ * The manifest module `contentLayer()` emits, as JavaScript source.
+ *
+ * Every value is a literal so the bundler can see it, and each body is a static
+ * import of a virtual module, which is the step no runtime cleverness replaces:
+ * a component is code, and only the bundler turns source into code.
+ *
+ * `bodies` is filled with the sources those virtual modules resolve to, each
+ * with the path of the entry it came from. A body module has no directory of
+ * its own, so a relative import inside it can only be resolved against that.
+ *
+ * `headings` holds the list the build measured for each Markdown entry, keyed
+ * the way `bodies` is. Markdown compiles to an HTML string, which carries no
+ * heading list, so without this a prebuilt page's table of contents is empty
+ * while the same file renders one at runtime.
+ */
+declare function manifestModule(collections: Record<string, LoadedEntry[]>, bodies: Map<string, Body>, headings?: ReadonlyMap<string, unknown>): string;
+/**
+ * Writes a value as JavaScript source, preserving what JSON would flatten.
+ *
+ * Refuses anything it cannot write exactly. The alternative is worse than an
+ * error: a `Map` would arrive as `{}` and a `NaN` as `null`, and the page built
+ * from it would be wrong with nothing to read in the build log. `where` names
+ * the entry in that message, because a build failure without one sends the
+ * reader through every file in the collection.
+ */
+declare function literal(value: unknown, where?: string, seen?: Set<object>): string;
+//#endregion
+export { BODY_PREFIX, Body, literal, manifestModule };

package/dist/codegen.mjs

@@ -0,0 +1,131 @@
+import { i as PREBUILT_MANIFEST_KEY } from "./symbols-DmXlrDbX.mjs";
+//#region src/codegen.ts
+/** The prefix of the virtual modules that carry each entry's raw body. */
+const BODY_PREFIX = "\0pitlane-content/entry/";
+/**
+* The manifest module `contentLayer()` emits, as JavaScript source.
+*
+* Every value is a literal so the bundler can see it, and each body is a static
+* import of a virtual module, which is the step no runtime cleverness replaces:
+* a component is code, and only the bundler turns source into code.
+*
+* `bodies` is filled with the sources those virtual modules resolve to, each
+* with the path of the entry it came from. A body module has no directory of
+* its own, so a relative import inside it can only be resolved against that.
+*
+* `headings` holds the list the build measured for each Markdown entry, keyed
+* the way `bodies` is. Markdown compiles to an HTML string, which carries no
+* heading list, so without this a prebuilt page's table of contents is empty
+* while the same file renders one at runtime.
+*/
+function manifestModule(collections, bodies, headings = /* @__PURE__ */ new Map()) {
+	let imports = [];
+	bodies.clear();
+	let entries = Object.entries(collections).map(([collection, loaded]) => {
+		let items = loaded.map((entry) => {
+			let where = `${collection}/${entry.id}`;
+			let fields = [`id: ${literal(entry.id, where)}`, `data: ${literal(entry.data, where)}`];
+			if (entry.filePath) fields.push(`filePath: ${literal(entry.filePath, where)}`);
+			if (entry.body) {
+				let binding = `body${bodies.size}`;
+				let id = `${BODY_PREFIX}${collection}/${entry.id}.${entry.body.format}`;
+				bodies.set(id, {
+					source: entry.body.source,
+					format: entry.body.format,
+					filePath: entry.filePath
+				});
+				imports.push(`import * as ${binding} from ${literal(id, where)};`);
+				fields.push(`body: ${bodyExpression(entry.body.format, binding, headings.get(id), where)}`);
+			}
+			return `{ ${fields.join(", ")} }`;
+		});
+		return `    [${literal(collection)}]: [${items.join(", ")}]`;
+	});
+	return [
+		...imports,
+		`globalThis[Symbol.for(${literal(PREBUILT_MANIFEST_KEY)})] = {`,
+		entries.join(",\n"),
+		"};",
+		""
+	].join("\n");
+}
+/**
+* MDX compiles to a module carrying a component and a heading list. Markdown
+* compiles to an HTML string, which `vite-plugin-satteri` exports as `html`,
+* so its heading list is written beside it.
+*/
+function bodyExpression(format, binding, headings, where) {
+	if (format === "mdx") return `{ format: "mdx", module: ${binding} }`;
+	return `{ format: "md", html: ${binding}.html ?? ${binding}.default${headings === void 0 ? "" : `, headings: ${literal(headings, where)}`} }`;
+}
+/**
+* Writes a value as JavaScript source, preserving what JSON would flatten.
+*
+* Refuses anything it cannot write exactly. The alternative is worse than an
+* error: a `Map` would arrive as `{}` and a `NaN` as `null`, and the page built
+* from it would be wrong with nothing to read in the build log. `where` names
+* the entry in that message, because a build failure without one sends the
+* reader through every file in the collection.
+*/
+function literal(value, where = "an entry", seen = /* @__PURE__ */ new Set()) {
+	if (value === void 0) return "undefined";
+	if (value === null) return "null";
+	if (typeof value === "string") return quote(value);
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "bigint") return `${value}n`;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw unwritable(where, value);
+		return Object.is(value, -0) ? "-0" : String(value);
+	}
+	if (typeof value !== "object") throw unwritable(where, value);
+	if (seen.has(value)) throw new Error(`${where} contains a cycle, which cannot be written into the manifest.`);
+	let nested = new Set(seen).add(value);
+	if (value instanceof Date) {
+		if (Number.isNaN(value.getTime())) throw unwritable(where, value);
+		return `new Date(${quote(value.toISOString())})`;
+	}
+	if (Object.getPrototypeOf(value) !== (Array.isArray(value) ? Array.prototype : Object.prototype)) throw unwritable(where, value);
+	let keys = Reflect.ownKeys(value);
+	if (Array.isArray(value)) {
+		let extra = keys.filter((key) => key !== "length" && !isIndex(key, value.length));
+		if (extra.length > 0) throw unwritableKey(where, extra[0]);
+		return `[${value.map((item) => literal(item, where, nested)).join(", ")}]`;
+	}
+	return `{ ${keys.map((key) => {
+		if (typeof key === "symbol") throw unwritableKey(where, key);
+		let descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (!descriptor?.enumerable || !("value" in descriptor)) throw unwritableKey(where, key);
+		if (key === "__proto__") throw unwritableKey(where, key);
+		return `${quote(key)}: ${literal(descriptor.value, where, nested)}`;
+	}).join(", ")} }`;
+}
+function isIndex(key, length) {
+	if (typeof key === "symbol") return false;
+	let index = Number(key);
+	return Number.isInteger(index) && index >= 0 && index < length;
+}
+function unwritableKey(where, key) {
+	let name = typeof key === "symbol" ? key.toString() : `"${key}"`;
+	return /* @__PURE__ */ new Error(`${where} has a key ${name} that cannot be written into the manifest.`);
+}
+/**
+* A quoted string, with the two separators `JSON.stringify` leaves raw.
+*
+* U+2028 and U+2029 are line terminators in JavaScript but not in JSON, so a
+* frontmatter value containing one would end the statement it sits in.
+*/
+function quote(text) {
+	return JSON.stringify(text).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function unwritable(where, value) {
+	return /* @__PURE__ */ new Error(`${where} produced ${describe(value)}, which cannot be written into the manifest.`);
+}
+function describe(value) {
+	if (typeof value === "number") return `the number ${String(value)}`;
+	if (typeof value === "function") return "a function";
+	if (typeof value === "symbol") return "a symbol";
+	if (typeof value === "object" && value !== null) return `a ${value.constructor?.name ?? "non-plain object"}`;
+	return `a ${typeof value}`;
+}
+//#endregion
+export { BODY_PREFIX, literal, manifestModule };

package/dist/hot.d.mts

@@ -0,0 +1,52 @@
+//#region src/hot.d.ts
+/** A file change the supervisor's watcher observed. */
+interface FileEvent {
+  event: "add" | "change" | "unlink";
+  filePath: string;
+}
+/** An event for the browser HMR client. A reload is the only one content sends. */
+interface BrowserEvent {
+  type: "reload";
+  files?: string[];
+}
+/**
+ * The part of `remix/node-hmr`'s `BrowserHmrChannel` this module uses.
+ *
+ * Declared structurally rather than imported, because importing the module
+ * that declares it would pull a Node-only dependency into every bundle this
+ * package reaches. {@link hotContent} holds the only import of it, loaded on
+ * demand behind its guard.
+ */
+interface BrowserHmrChannel {
+  readonly url: string;
+  close(): void;
+  onFileEvents(handler: (events: readonly FileEvent[]) => Promise<readonly BrowserEvent[]>): () => void;
+  updateWatchedFiles(delta: {
+    add: readonly string[];
+    remove: readonly string[];
+  }): void;
+}
+/**
+ * Reloads the browser when a file behind a collection changes.
+ *
+ * Call it once, beside `createContent`, and leave it in for production: it
+ * does nothing unless `remix/node-hmr` is supervising the process, which is
+ * what a `dev` command does and a production server does not. That is also why
+ * the import below is loaded on demand. `remix/node-hmr/runtime` is Node-only
+ * and can only be imported by a supervised child, so a static import would
+ * follow this module into a Worker bundle.
+ *
+ * @param content The object `createContent` returned.
+ */
+declare function hotContent(content: Record<string, unknown>): Promise<void>;
+/**
+ * The watching itself, over a channel someone else opened.
+ *
+ * Separated from {@link hotContent} so it can be driven by a channel a test
+ * controls: the real one exists only inside a process `remix/node-hmr` started.
+ *
+ * @internal
+ */
+declare function watchCollections(content: Record<string, unknown>, channel: BrowserHmrChannel, root: string): Promise<void>;
+//#endregion
+export { BrowserEvent, BrowserHmrChannel, FileEvent, hotContent, watchCollections };

package/dist/hot.mjs

@@ -0,0 +1,65 @@
+import { t as HOT_COLLECTION } from "./symbols-DmXlrDbX.mjs";
+import { contentRoot } from "./prebuild.mjs";
+import * as path from "node:path";
+//#region src/hot.ts
+/**
+* Reloads the browser when a file behind a collection changes.
+*
+* Call it once, beside `createContent`, and leave it in for production: it
+* does nothing unless `remix/node-hmr` is supervising the process, which is
+* what a `dev` command does and a production server does not. That is also why
+* the import below is loaded on demand. `remix/node-hmr/runtime` is Node-only
+* and can only be imported by a supervised child, so a static import would
+* follow this module into a Worker bundle.
+*
+* @param content The object `createContent` returned.
+*/
+async function hotContent(content) {
+	if (!process.env.REMIX_NODE_HMR) return;
+	let { createBrowserHmrChannel } = await import("remix/node-hmr/runtime");
+	await watchCollections(content, await createBrowserHmrChannel(), contentRoot());
+}
+/**
+* The watching itself, over a channel someone else opened.
+*
+* Separated from {@link hotContent} so it can be driven by a channel a test
+* controls: the real one exists only inside a process `remix/node-hmr` started.
+*
+* @internal
+*/
+async function watchCollections(content, channel, root) {
+	/** Which collection each watched file belongs to, so an event finds its owner. */
+	let owners = /* @__PURE__ */ new Map();
+	for (let collection of Object.values(content)) {
+		let hot = handle(collection);
+		if (!hot) continue;
+		let watched = [];
+		hot.onPopulated((files) => {
+			let absolute = files.map((file) => path.resolve(root, file));
+			channel.updateWatchedFiles({
+				add: absolute,
+				remove: watched
+			});
+			for (let file of watched) owners.get(file)?.delete(hot);
+			for (let file of absolute) {
+				let set = owners.get(file) ?? /* @__PURE__ */ new Set();
+				set.add(hot);
+				owners.set(file, set);
+			}
+			watched = absolute;
+		});
+	}
+	channel.onFileEvents(async (events) => {
+		let stale = /* @__PURE__ */ new Set();
+		for (let { filePath } of events) for (let owner of owners.get(path.resolve(root, filePath)) ?? []) stale.add(owner);
+		if (stale.size === 0) return [];
+		for (let collection of stale) collection.invalidate();
+		return [{ type: "reload" }];
+	});
+}
+function handle(collection) {
+	if (typeof collection !== "object" || collection === null) return void 0;
+	return collection[HOT_COLLECTION];
+}
+//#endregion
+export { hotContent, watchCollections };

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+import { _ as Reference, a as ContentBuilder, c as EntryBody, d as LiveEntry, f as LiveLoader, h as LoaderContext, i as Content, l as GenerateIdOptions, m as Loader, n as CollectionDefinition, o as ContentLoader, p as LoadedEntry, r as CollectionEntry, s as Entry, t as Collection, u as Heading, v as RenderedEntry } from "./types-xSR1WTBq.mjs";
+//#region src/content.d.ts
+/**
+ * Declares a set of content collections.
+ *
+ * Returns the collection object synchronously without loading entries.
+ * Reads and rendering remain asynchronous. Declaration errors throw here.
+ *
+ * Under `contentLayer()`, registers deferred population work. The plugin
+ * awaits it after evaluating the declarations and before emitting the bundle.
+ */
+declare function createContent<T extends Record<string, CollectionDefinition>>(build: (c: ContentBuilder) => T): Content<T>;
+//#endregion
+export { type Collection, type CollectionDefinition, type CollectionEntry, type ContentBuilder, type ContentLoader, type Entry, type EntryBody, type GenerateIdOptions, type Heading, type LiveEntry, type LiveLoader, type LoadedEntry, type Loader, type LoaderContext, type Reference, type RenderedEntry, createContent };