@mosetta/content 0.0.0-stage → 0.0.10

package/src/i18n.ts

@@ -0,0 +1,177 @@
+// LANGUAGE ADDRESSING and the TRANSLATOR PORT — the only part of localization the platform
+// owns. Which languages a project's addresses serve is its content config (`config.json`:
+// `languages`, `defaultLanguage`); the language of a request is the first path segment when it
+// names one (`/ru/blog/x`), the default otherwise. The WORDS in each language are not here: they
+// belong to a block (a reference provider) the page places like any other, which reads the
+// request's language off the route — all but the page's words ABOUT itself (its meta's title and
+// description), which the head and the article lists need before any block renders: the meta
+// carries them per language. The translator is a host service behind a port.
+
+export interface ILanguages {
+  /** ISO 639-1 codes, the default first */
+  readonly languages: readonly string[];
+  readonly defaultLanguage: string;
+}
+
+export const DEFAULT_LANGUAGES: ILanguages = { languages: ['en'], defaultLanguage: 'en' };
+
+const CODE_RE = /^[a-z]{2}(-[a-z]{2})?$/i;
+
+/** the content config's language block, validated; anything odd → the single default */
+export function parseLanguages(config: unknown): ILanguages {
+  const raw = config as { languages?: unknown; defaultLanguage?: unknown } | null;
+  const list = Array.isArray(raw?.languages) ? raw.languages.filter((l): l is string => typeof l === 'string' && CODE_RE.test(l)).map((l) => l.toLowerCase()) : [];
+  if (!list.length) return DEFAULT_LANGUAGES;
+  const preferred = typeof raw?.defaultLanguage === 'string' ? raw.defaultLanguage.toLowerCase() : list[0];
+  const defaultLanguage = list.includes(preferred) ? preferred : list[0];
+  return { languages: [defaultLanguage, ...list.filter((l) => l !== defaultLanguage)], defaultLanguage };
+}
+
+export interface ILanguageOfPath {
+  readonly lang: string;
+  /** the path with the language prefix removed — what the route table is matched against */
+  readonly pathname: string;
+  /** the request named the language in the path (the default may be named too) */
+  readonly prefixed: boolean;
+}
+
+import { languageScheme } from '@mosetta/core';
+
+export { isRightToLeft, pathInLanguage } from '@mosetta/core';
+
+/** `/ru/blog/x` → ru + `/blog/x`; `/blog/x` → the default; an unknown first segment is not a language */
+export function languageOfPath(pathname: string, languages: ILanguages): ILanguageOfPath {
+  const { lang, path, named } = languageScheme('prefix').read(pathname, languages);
+  return { lang, pathname: path, prefixed: named };
+}
+
+// ---- the page's words about itself, in a language ----
+
+interface IMetaWithWords {
+  readonly title?: string;
+  readonly description?: string;
+  readonly i18n?: Readonly<Record<string, { readonly title?: string; readonly description?: string }>>;
+}
+
+/**
+ * The meta a reader of `lang` gets: the title and description in their language where the page
+ * has them, the original otherwise. The other languages are left out — a reader never needs them.
+ */
+export function metaInLanguage<TMeta extends IMetaWithWords>(meta: TMeta | undefined, lang: string): Omit<TMeta, 'i18n'> | undefined {
+  if (!meta) return meta;
+  const { i18n, ...own } = meta;
+  const words = i18n && typeof i18n === 'object' ? i18n[lang] : undefined;
+  if (!words || typeof words !== 'object') return own;
+  const out: Record<string, unknown> = { ...own };
+  for (const key of ['title', 'description'] as const) {
+    const word = words[key];
+    if (typeof word === 'string' && word.trim()) out[key] = word;
+  }
+  return out as Omit<TMeta, 'i18n'>;
+}
+
+// ---- translation: the port, the wire protocol, the shared handler ----
+
+/** one string to translate, and what it is on the page */
+export interface ITranslateSegment {
+  readonly text: string;
+  /** what reads it — the block and its setting (`heading · text`, `button · text`), or `page title` */
+  readonly role?: string;
+}
+
+/** what a translator is told about the page as a whole */
+export interface ITranslateContext {
+  /** what the page is: its title and description in the original */
+  readonly page?: string;
+  /** the author's notes: what to leave untranslated, the tone, the terms */
+  readonly instructions?: string;
+}
+
+/**
+ * The TRANSLATOR PORT: the strings of one page in, the same strings translated out, in the same
+ * order. The strings come in the page's order, each with what it is on the page, together with
+ * what the page is about and the author's notes — a heading, a button and a table cell are
+ * translated differently, and an English lesson keeps its English examples. Where the words come
+ * from is the host's business (a Workers AI model, a paid API, an echo in dev).
+ */
+export interface ITranslator {
+  translate(segments: readonly ITranslateSegment[], from: string, to: string, context: ITranslateContext): Promise<readonly string[]>;
+}
+
+/** dev's translator: marks the string with the target language, so a "translation" is visibly one */
+export const echoTranslator: ITranslator = {
+  translate: (segments, _from, to) => Promise.resolve(segments.map(({ text }) => `[${to}] ${text}`)),
+};
+
+/** the host's translation endpoint — POST an ITranslateRequest, receive an ITranslateResponse */
+export const TRANSLATE_PATH = '/__mosetta__/translate';
+
+export interface ITranslateItem {
+  readonly id: string;
+  readonly text: string;
+  readonly role?: string;
+}
+
+export interface ITranslateRequest {
+  readonly from: string;
+  readonly to: string;
+  /** in the page's order */
+  readonly items: readonly ITranslateItem[];
+  readonly context?: ITranslateContext;
+}
+
+export interface ITranslateResponse {
+  readonly items: readonly { readonly id: string; readonly text: string }[];
+}
+
+export const MAX_TRANSLATE_ITEMS = 200;
+export const MAX_TRANSLATE_CHARS = 40_000;
+/** the longest role, page summary and notes the endpoint accepts */
+export const MAX_TRANSLATE_ROLE = 200;
+export const MAX_TRANSLATE_CONTEXT = 4000;
+
+const jsonResponse = (body: unknown, status: number): Response => new Response(JSON.stringify(body), {
+  status,
+  headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+});
+
+/**
+ * The endpoint every host shares: validates the request, asks the translator, answers item by
+ * item. The host decides WHO may call it (an editor's session on the platform, anyone in dev)
+ * and WHICH translator answers — `null` says the host has none (501).
+ */
+export async function handleTranslate(request: Request, translator: ITranslator | null): Promise<Response> {
+  if (request.method !== 'POST') return jsonResponse({ error: { code: 'METHOD_NOT_ALLOWED' } }, 405);
+  if (!translator) return jsonResponse({ error: { code: 'NO_TRANSLATOR', message: 'this host has no translator configured' } }, 501);
+  let body: ITranslateRequest;
+  try {
+    body = (await request.json()) as ITranslateRequest;
+  } catch {
+    return jsonResponse({ error: { code: 'BAD_JSON' } }, 400);
+  }
+  const { from, to } = body ?? {};
+  if (typeof from !== 'string' || !CODE_RE.test(from) || typeof to !== 'string' || !CODE_RE.test(to) || from === to) {
+    return jsonResponse({ error: { code: 'BAD_LANGUAGES' } }, 400);
+  }
+  const items: readonly ITranslateItem[] = Array.isArray(body.items) ? (body.items as ITranslateItem[]) : [];
+  if (!items.length || items.length > MAX_TRANSLATE_ITEMS
+    || items.some((i) => !i || typeof i.id !== 'string' || typeof i.text !== 'string' || !i.text.trim())
+    || items.some((i) => i.role !== undefined && (typeof i.role !== 'string' || i.role.length > MAX_TRANSLATE_ROLE))
+    || items.reduce((n, i) => n + i.text.length, 0) > MAX_TRANSLATE_CHARS) {
+    return jsonResponse({ error: { code: 'BAD_ITEMS' } }, 400);
+  }
+  const raw = (body.context ?? {}) as Record<string, unknown>;
+  const contextText = (value: unknown): string | undefined => (typeof value === 'string' && value.trim() ? value.trim() : undefined);
+  const context: ITranslateContext = { page: contextText(raw.page), instructions: contextText(raw.instructions) };
+  if ((context.page?.length ?? 0) > MAX_TRANSLATE_CONTEXT || (context.instructions?.length ?? 0) > MAX_TRANSLATE_CONTEXT) {
+    return jsonResponse({ error: { code: 'BAD_CONTEXT' } }, 400);
+  }
+  try {
+    const texts = await translator.translate(items.map((i) => ({ text: i.text, ...(i.role ? { role: i.role } : {}) })), from, to, context);
+    if (texts.length !== items.length) throw new Error(`translator answered ${texts.length} of ${items.length}`);
+    const answer: ITranslateResponse = { items: items.map((item, i) => ({ id: item.id, text: texts[i] })) };
+    return jsonResponse(answer, 200);
+  } catch (e) {
+    return jsonResponse({ error: { code: 'TRANSLATION_FAILED', message: String((e as Error)?.message ?? e) } }, 502);
+  }
+}

package/src/media.ts

@@ -0,0 +1,69 @@
+// MEDIA: pictures and videos an author uploads from a settings form. They live in the project's
+// PUBLIC media store (its CDN folder) under `media/…` — a public asset like a module's css. The
+// browser puts the file there itself, through an address the Worker signed for exactly that key,
+// type and size (a video does not travel through a server action). The rules are pure data: what
+// may go up, how big, and under which key.
+const IMAGE_TYPES: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/avif': 'avif',
+};
+
+// played by the browser as uploaded: no transcoding, so only what every browser plays
+const VIDEO_TYPES: Record<string, string> = {
+  'video/mp4': 'mp4',
+  'video/webm': 'webm',
+};
+
+export type TMediaKind = 'image' | 'video';
+
+/** the largest picture accepted — bytes */
+export const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+
+/** the largest video accepted — bytes */
+export const MAX_VIDEO_BYTES = 100 * 1024 * 1024;
+
+export const MEDIA_PREFIX = 'media/';
+
+/** where the editor asks its host to sign an upload (the host answers it itself) */
+export const MEDIA_UPLOAD_PATH = '/__mosetta__/media/upload';
+
+/** raster images and web video only: an svg can carry script, and no page needs one uploaded */
+export function mediaKindOf(type: string): TMediaKind | null {
+  if (Object.hasOwn(IMAGE_TYPES, type)) return 'image';
+  if (Object.hasOwn(VIDEO_TYPES, type)) return 'video';
+  return null;
+}
+
+export const isAllowedMediaType = (type: string): boolean => mediaKindOf(type) !== null;
+
+/** what the browser offers in the file picker for a kind */
+export const acceptedTypes = (kind: TMediaKind): string => Object.keys(kind === 'image' ? IMAGE_TYPES : VIDEO_TYPES).join(',');
+
+const megabytes = (bytes: number): string => `${Math.round((bytes / 1024 / 1024) * 10) / 10} MB`;
+
+/** why a file cannot go up, in words for its author — or null when it can */
+export function mediaIssue(type: string, size: number): string | null {
+  const kind = mediaKindOf(type);
+  if (!kind) return `${type || 'this file'} is not a picture (png, jpeg, gif, webp, avif) or a video (mp4, webm)`;
+  if (!Number.isInteger(size) || size <= 0) return 'the file is empty';
+  const limit = kind === 'image' ? MAX_IMAGE_BYTES : MAX_VIDEO_BYTES;
+  return size > limit ? `the ${kind} is ${megabytes(size)} — the limit is ${megabytes(limit)}` : null;
+}
+
+/**
+ * The object key of an upload: `media/<yyyy>/<mm>/<stamp>-<slug>.<ext>` — the stamp makes it
+ * unique (so the CDN may cache it forever), the slug keeps the original name readable, the
+ * extension follows the declared type, never the name.
+ */
+export function mediaObjectKey(name: string, type: string, now: Date = new Date()): string {
+  const ext = IMAGE_TYPES[type] ?? VIDEO_TYPES[type];
+  if (!ext) throw new Error(`media: unsupported type ${type}`);
+  const base = name.replace(/\.[^.]*$/, '').toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'media';
+  const stamp = now.getTime().toString(36);
+  const yyyy = now.getUTCFullYear();
+  const mm = String(now.getUTCMonth() + 1).padStart(2, '0');
+  return `${MEDIA_PREFIX}${yyyy}/${mm}/${stamp}-${base}.${ext}`;
+}

package/src/model.ts

@@ -0,0 +1,300 @@
+// Content domain model: pages and prefabs are revisioned entities.
+//
+// TWO separate axes (they used to share one):
+//  - VERSIONS — the publish history: an integer axis assigned at publish time (no semver — content
+//    has no API-compat semantics); exactly one version per entity is `published` (= live), the rest
+//    are `archived`, all of them immutable.
+//  - DRAFTS — a flat, unordered set of working copies, each under its own random id. Drafts are
+//    NOT in the meta: recording them there would make the meta a shared write hotspot between
+//    concurrent editors — the exact race the split exists to remove. They are a prefix LISTING.
+
+export type ContentKind = 'pages' | 'prefabs';
+
+export type RevisionStatus = 'published' | 'archived';
+
+export type PrefabType = 'page' | 'unit';
+
+// The per-entity meta document (`pages/<name>/page.json` / `prefabs/<name>/prefab.json`).
+// Mutated ONLY at publish — a rare, owner-visible operation; draft churn never touches it.
+export interface IContentMeta {
+  /** the published (live) version, or null while nothing is published yet */
+  readonly live: number | null;
+  /** every published-ever version (stringified int key) → its status; exactly one is 'published' */
+  readonly versions: Record<string, RevisionStatus>;
+  /** the names given at publish, by version — a publication may be called something */
+  readonly names?: Record<string, string>;
+  /** prefabs only: what the prefab is a template of (previously encoded in the file name) */
+  readonly type?: PrefabType;
+  /**
+   * FROZEN by the platform (the workbench page of a platform project): no new draft, no publish,
+   * no delete — and no other page may publish under its route. Its content is a live reference, so
+   * it never needs editing; the platform's deploy changes what it becomes.
+   */
+  readonly locked?: boolean;
+}
+
+// ---- drafts ----------------------------------------------------------------------------------
+
+/**
+ * The WORKING fields a draft document carries on top of its content. They live inline in the doc
+ * (not in an envelope) so every reader of a draft — preview, ssr, the editor — sees the same shape
+ * a published document has; publish strips them the way it strips history/redo.
+ */
+export interface IDraftFields {
+  /**
+   * The draft's write sequence — the optimistic-concurrency token. Every accepted save must carry
+   * exactly `stored.seq + 1`: a writer that fell behind (someone else saved meanwhile) breaks the
+   * chain and is refused at the trust boundary (412), which the editor answers with fork-or-rollback.
+   */
+  readonly seq: number;
+  /** ISO timestamp of the draft's creation */
+  readonly createdAt: string;
+  /** the published version this draft's lineage started from; absent when none was published */
+  readonly baseRev?: number;
+  /** an optional human label for pickers/tabs */
+  readonly title?: string;
+}
+
+/** what a draft listing returns per draft — the fields, never the content */
+export interface IDraftSummary extends IDraftFields {
+  readonly id: string;
+  /** the route the draft would publish under — a page's; read with the summary, the doc is at hand */
+  readonly pattern?: string;
+}
+
+/** draft ids are random (no coordination on create); dot-free so a preview token can carry one */
+export const DRAFT_ID_RE = /^[a-z0-9][a-z0-9-]{5,63}$/;
+
+/** the published form of a draft document: every working field stripped */
+export function publishedFormOf<T extends object>(doc: T): Omit<T, 'history' | 'redo' | keyof IDraftFields> {
+  const {
+    history: _history, redo: _redo, seq: _seq, createdAt: _createdAt, baseRev: _baseRev, title: _title, ...body
+  } = doc as T & Partial<IDraftFields> & { history?: unknown; redo?: unknown };
+  return body;
+}
+
+/** the slot a child belongs to when it names none — spelled out where the tree is manipulated */
+export const DEFAULT_SLOT = 'default';
+
+// A tree node as persisted in content documents. Deliberately self-contained (not imported from the
+// legacy @mosetta/core): the JSON contract is owned by this package — includes the
+// node-settings target model (`settings`) the runtime types will converge to.
+export interface IBlueprintNodeDoc {
+  readonly id: string;
+  /** canonical full module name: _ns_<ns>_t_<type>_n_<name>_v_<version> */
+  readonly reference: string;
+  readonly children: IBlueprintNodeDoc[];
+  readonly slot?: string;
+  readonly settings?: Record<string, unknown>;
+  /** effective-ssr flag (SSR epic): true on the ROOT enables server rendering; false opts a
+   * branch out (not re-enablable deeper — no islands); absent → inherit */
+  readonly ssr?: boolean;
+  /**
+   * A PROVIDER that takes new blocks under its wing: a block placed in its reach (inserted,
+   * pasted) gets its bindable fields of the provider's type linked to it at once. The editor's
+   * business — no renderer reads it.
+   */
+  readonly autoBind?: boolean;
+}
+
+// What was done to a page tree — the unit the draft's history is made of. One entry per mutation,
+// structured so a history UI can list it and an undo can act on it without parsing prose.
+export interface IPageAction {
+  readonly type: 'insert' | 'remove' | 'settings' | 'ssr' | 'paste' | 'cut' | 'move';
+  /** for a paste — the first arriving block's fresh id; the whole paste is ONE step */
+  readonly nodeId: string;
+  /** insert only: the module that went in */
+  readonly reference?: string;
+}
+
+/** a page snapshot as stored inside history/redo entries: both stacks stripped — entries never
+ * nest, or the JSON would grow without bound */
+export type TPageSnapshot = Omit<IPageDoc, 'history' | 'redo'>;
+
+/** one step of a draft's history: the action, and the page as it was BEFORE it */
+export interface IPageHistoryEntry {
+  readonly action: IPageAction;
+  readonly before: TPageSnapshot;
+}
+
+/** an undone step waiting on the redo list: the action, and the page as it was AFTER it */
+export interface IPageRedoEntry {
+  readonly action: IPageAction;
+  readonly after: TPageSnapshot;
+}
+
+/** how many steps a draft remembers; the oldest falls off, keeping the JSON bounded */
+export const PAGE_HISTORY_LIMIT = 20;
+
+// A page document — the exact flat shape the render path consumes (public/pages/<name>.json).
+// A DRAFT of it additionally carries the working fields (IDraftFields) and the undo stacks;
+// publish strips them all — a published version is pure content.
+/**
+ * What a page says ABOUT itself — the head tags, the entry in an article list, the share card.
+ * Versioned with the document like the pattern is. Every field optional: a page without meta is
+ * a page with an empty head.
+ */
+export interface IPageMeta {
+  readonly title?: string;
+  readonly description?: string;
+  /** an absolute URL of the cover / share image */
+  readonly image?: string;
+  /** ISO date (YYYY-MM-DD) — what an article list sorts by */
+  readonly date?: string;
+  /** the category an article list filters by (`?category=<key>`) */
+  readonly category?: string;
+  /** kept out of search engines: `robots: noindex` in the head, left out of the sitemap */
+  readonly noindex?: boolean;
+  /**
+   * The words in the project's other languages, by language code: a reader of `/ru/…` gets the
+   * Russian title and description, a field left out reads the original
+   */
+  readonly i18n?: Readonly<Record<string, IPageMetaWords>>;
+}
+
+/** the part of a page's meta that is words — what a translation gives in another language */
+export interface IPageMetaWords {
+  readonly title?: string;
+  readonly description?: string;
+}
+
+/** a setting of one of a prefab's blocks each instance sets for itself */
+export interface IPrefabField {
+  /** the block's id as the prefab authored it */
+  readonly node: string;
+  readonly setting: string;
+  /** what the instance's form calls it */
+  readonly label: string;
+}
+
+export interface IPageDoc extends IBlueprintNodeDoc, Partial<IDraftFields> {
+  /** route pattern; versioned WITH the doc so publishing changes the route atomically */
+  readonly pattern: string;
+  /**
+   * A PREFAB's open fields — carried only by a prefab opened in the editor, which edits every tree
+   * in a page's shape (see prefabAsPage); a page has none
+   */
+  readonly fields?: readonly IPrefabField[];
+  readonly meta?: IPageMeta;
+  readonly fallback?: string;
+  readonly devOnly?: boolean;
+  /** the draft's working memory (undo); publish strips it — a published page carries none */
+  readonly history?: readonly IPageHistoryEntry[];
+  /** steps undone and waiting to be redone; in the document like history is — it would be
+   * surprising for one direction to survive a reload and the other not. A fresh edit clears it */
+  readonly redo?: readonly IPageRedoEntry[];
+}
+
+// A prefab document. `type` lives in the meta, not here; drafts carry the working fields too.
+export interface IPrefabDoc extends Partial<IDraftFields> {
+  readonly root: IBlueprintNodeDoc;
+  /** the settings each instance sets for itself */
+  readonly fields?: readonly IPrefabField[];
+  readonly attributes?: Record<string, unknown>;
+  readonly devOnly?: boolean;
+  /** a draft's undo memory, in the page shape the editor edits it in */
+  readonly history?: readonly IPageHistoryEntry[];
+  readonly redo?: readonly IPageRedoEntry[];
+}
+
+export interface IContentEntity {
+  readonly name: string;
+  readonly meta: IContentMeta;
+  /** the entity's drafts (listing + working fields) — the meta knows nothing about them */
+  readonly drafts: readonly IDraftSummary[];
+}
+
+/** a loaded PUBLISHED (or archived) version */
+export interface ILoadedContent<TDoc> {
+  readonly name: string;
+  readonly meta: IContentMeta;
+  readonly rev: number;
+  readonly doc: TDoc;
+}
+
+/** a loaded draft — identified by its id, no meta involved */
+export interface ILoadedDraft<TDoc> {
+  readonly name: string;
+  readonly id: string;
+  readonly doc: TDoc;
+}
+
+// Catalog: built from the provider's `public/modules.json` — a single catalog of entities
+// (own modules + packaged ones); a descriptor = {id, reference, assets, dependencies}.
+export interface IModuleDescriptorReference {
+  readonly namespace: string;
+  readonly name: string;
+  readonly type: string;
+  readonly version: string;
+}
+
+export interface IModuleDescriptor {
+  readonly id: string;
+  readonly reference: IModuleDescriptorReference;
+  readonly assets?: readonly string[];
+  readonly dependencies?: readonly string[];
+  /**
+   * A PAGE ROOT: the module a page names as its own root, not a block to place inside one. Stamped
+   * by the build from the definer the facet imported; absent on everything else.
+   */
+  readonly isRoot?: boolean;
+  /**
+   * An INTERNAL block: a tool's own (an editor panel, the workbench shell, the editor's fallback),
+   * placed by the platform's pages and never offered to an author. Stamped by the build from the
+   * `markInternalTile` import the facet made; absent on everything else.
+   */
+  readonly internal?: boolean;
+}
+
+export interface ICatalogEntry extends IModuleDescriptor {
+  /** a paired `editor`-facet module (same namespace+name+version) exists → the editor has a settings form */
+  readonly hasEditor: boolean;
+  /** the block's icon (`<name>.icon.svg` beside its module), where it can be fetched; absent — none */
+  readonly iconUrl?: string;
+}
+
+/**
+ * A PREFAB a library brings (the catalog names it beside its distribution's blocks): placed on a
+ * page, it is LIVE — `reference` names no version, the page always takes its current form.
+ */
+export interface ILibraryPrefabEntry {
+  readonly namespace: string;
+  readonly name: string;
+  /** the distribution version that brought it */
+  readonly version: string;
+  /** what a page names to place it: `_ns_<namespace>_t_prefab_n_<name>_v_live` */
+  readonly reference: string;
+}
+
+/**
+ * A DISTRIBUTION as its catalog entity describes it (`mosetta.json` of its package): what it is
+ * called, what it brings, its pictures, where its source lives. `internal` — a tool's own (the
+ * editor): no blocks for authors.
+ */
+export interface IDistributionEntry {
+  readonly id: string;
+  readonly namespace: string;
+  readonly version: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly source?: string;
+  readonly iconUrl?: string;
+  readonly coverUrl?: string;
+  readonly internal?: boolean;
+  /** the distribution others are built on (the UI kit): always connected */
+  readonly base?: boolean;
+  /** what this version says it changed — its section of the distribution's CHANGELOG.md */
+  readonly changes?: string;
+}
+
+// Validation primitives shared by the zod factories and any plain-JS consumer (the node provider).
+// Mirrors the canonical encoding in cli/runtime/naming.js — validation-only, not a parser.
+export const CANONICAL_REFERENCE_RE = /^_ns_[A-Za-z0-9._-]+_t_[a-z][A-Za-z0-9]*_n_[A-Za-z0-9._-]+_v_[A-Za-z0-9_]+$/;
+
+// Entity names follow the module/prefab naming convention: lowerCamel, alphanumeric.
+export const ENTITY_NAME_RE = /^[a-z][A-Za-z0-9]*$/;
+
+export function maxRevision(meta: IContentMeta): number | null {
+  const revs = Object.keys(meta.versions).map(Number).filter((n) => Number.isInteger(n) && n > 0);
+  return revs.length ? Math.max(...revs) : null;
+}

package/src/names.ts

@@ -0,0 +1,50 @@
+// A NAME for a draft: two friendly words, drawn from the draft's id — `brave-otter`. A draft
+// used to be known by the first eight characters of its id, which nobody can tell apart or
+// remember; a name of words is what services give a thing the author did not name yet. Drawn
+// from the id so it never has to be stored to be stable (it is stored anyway, as the draft's
+// title, where the author may change it later).
+
+const ADJECTIVES = [
+  'amber', 'bold', 'brave', 'breezy', 'bright', 'calm', 'cheery', 'clever', 'cosmic', 'crisp',
+  'dapper', 'daring', 'dusty', 'eager', 'early', 'fancy', 'fresh', 'frosty', 'gentle', 'glad',
+  'golden', 'happy', 'hearty', 'honest', 'humble', 'jolly', 'keen', 'kind', 'leafy', 'lively',
+  'lucky', 'lunar', 'merry', 'mighty', 'misty', 'mossy', 'nimble', 'noble', 'plucky', 'polite',
+  'proud', 'quick', 'quiet', 'rapid', 'rosy', 'royal', 'rusty', 'sandy', 'shiny', 'silent',
+  'sleek', 'smart', 'snowy', 'solid', 'steady', 'stormy', 'sunny', 'swift', 'tender', 'tidy',
+  'velvet', 'vivid', 'warm', 'wise', 'witty', 'young', 'zesty',
+];
+
+const NOUNS = [
+  'acorn', 'anchor', 'badger', 'beacon', 'bramble', 'canyon', 'cedar', 'clover', 'comet', 'delta',
+  'dune', 'eagle', 'ember', 'falcon', 'fern', 'finch', 'fjord', 'garnet', 'glacier', 'grove',
+  'harbor', 'hazel', 'heron', 'hollow', 'iris', 'island', 'ivory', 'jasper', 'juniper', 'kelp',
+  'kestrel', 'lagoon', 'lantern', 'lotus', 'mango', 'maple', 'marble', 'meadow', 'nebula', 'nutmeg',
+  'oak', 'orchid', 'otter', 'pebble', 'pine', 'prairie', 'quartz', 'quill', 'raven', 'reef',
+  'river', 'saffron', 'sage', 'thistle', 'tulip', 'tundra', 'umber', 'valley', 'violet', 'walnut',
+  'willow', 'wren', 'yarrow', 'zephyr',
+];
+
+/** the longest name a publication may be given */
+export const MAX_REVISION_TITLE = 80;
+
+function digest(text: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+/** the two words a seed (a draft's id) names: the same seed, the same words */
+export function draftTitleOf(seed: string): string {
+  const hash = digest(seed);
+  return `${ADJECTIVES[hash % ADJECTIVES.length]}-${NOUNS[(hash >>> 8) % NOUNS.length]}`;
+}
+
+/** a publication's name as stored: trimmed, bounded; empty — none */
+export function revisionTitleOf(title: unknown): string | null {
+  if (typeof title !== 'string') return null;
+  const trimmed = title.trim().slice(0, MAX_REVISION_TITLE);
+  return trimmed || null;
+}