@frontlit/text-editor 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -58,3 +58,48 @@ import "@frontlit/text-editor/styles.css";
 ## License
 
 MIT
+# Documentation content profile
+
+`@frontlit/text-editor/docs` is a server-safe entry for documentation validation,
+CommonMark/GFM conversion, bounded YAML frontmatter, source-path mapping, and
+versioned content hashes (DM-VALIDATE, DM-CONVERT, DM-SOURCE, DM-ROUTE). It does
+not load React or instantiate an editor, node view, or upload control. Import
+`@frontlit/text-editor/headings` for the lightweight heading policy alone.
+
+```ts
+import { parseDocsMarkdown, serializeDocsMarkdown, validateDocsContent } from "@frontlit/text-editor/docs";
+
+const { content, frontmatter } = parseDocsMarkdown(markdown, { file: "manual/setup.md" });
+const report = validateDocsContent(content);
+const exported = serializeDocsMarkdown(content, frontmatter);
+```
+
+Parsing requires frontmatter with a title by default. Use `{ frontmatter: false }`
+for editor Markdown bodies with metadata supplied separately. Unsupported content
+throws `DocsContentError` with structured diagnostics; validation returns a report
+without replacing invalid input with an empty document. A serialization failure
+must prevent a draft write.
+
+The profile supports paragraphs, headings 1–6, bold/italic/strike/inline-code/link
+marks, nested lists, blockquotes, fenced code, horizontal rules, block images,
+and rectangular tables with one header row and one paragraph per cell. It rejects
+raw HTML/MDX, task lists, footnotes, inline images, merged/multiblock/aligned tables,
+resize attributes, and unsupported marks. Images require stable HTTPS URLs.
+URL syntax checks do not establish asset ownership or prove third-party privacy;
+the API must verify managed-media provenance separately (DM-MEDIA).
+
+Normalizations apply schema defaults, retain an omitted root array as `[]`, and
+represent absent image alt descriptions as `""`. Markdown semantic comparisons
+ignore empty top-level paragraphs used for spacing; canonical JSON retains them.
+Unknown frontmatter stays bounded plain data. YAML aliases, custom tags, duplicate
+keys, and prototype-sensitive metadata keys are rejected. Module safety ceilings
+are 1 MiB of Markdown/text, 20,000 nodes, depth 64, and 32 KiB of metadata; request
+transport limits can be smaller. Production admission limits remain a separate
+operator configuration concern.
+
+Use `<Editor profile="documentation" />` and
+`<TextRenderer profile="documentation" />` for docs. The editor omits unsupported
+controls and requires a media picker for uploads. Heading IDs use Unicode text,
+remove punctuation, and assign unique suffixes in document order. Docs navigation,
+validation helpers, rendering, and retrieval use the same policy; the default
+editor/renderer profile preserves general-purpose behavior.

package/dist/docs.d.ts

@@ -0,0 +1,90 @@
+import { Extensions, JSONContent } from '@tiptap/core';
+import { Schema } from '@tiptap/pm/model';
+export { DOCS_HEADING_POLICY_VERSION, HeadingNode, createHeadingIdGenerator, docsNodeText, extractDocsHeadings } from './headings.js';
+
+/** DM-VALIDATE: shared, deterministic reports for authoring and import. */
+interface DocsDiagnostic {
+    code: string;
+    severity: "error" | "warning";
+    blocksSave: boolean;
+    blocksPublish: boolean;
+    message: string;
+    fieldPath?: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    route?: string;
+    documentId?: string;
+    relatedFiles?: string[];
+}
+declare function diagnostic(code: string, message: string, location?: Partial<DocsDiagnostic>): DocsDiagnostic;
+declare function sortDiagnostics(items: DocsDiagnostic[]): DocsDiagnostic[];
+declare class DocsContentError extends Error {
+    readonly diagnostics: DocsDiagnostic[];
+    constructor(diagnostics: DocsDiagnostic[]);
+}
+
+/** DM-VALIDATE: schema-only extensions; no React, upload controls, or node views. */
+declare function createDocsExtensions(): Extensions;
+declare const docsSchema: Schema;
+declare const DOCS_SCHEMA_VERSION = 1;
+
+/** DM-VALIDATE/DM-MEDIA: syntax safety; ownership/provider checks belong to the API. */
+declare function isSafeDocsUrl(value: unknown, image?: boolean): value is string;
+
+declare const DOCS_LIMITS: {
+    readonly bytes: number;
+    readonly nodes: 20000;
+    readonly depth: 64;
+    readonly metadataBytes: 32768;
+};
+/** Checks before ProseMirror can discard unknown keys. Never repairs supplied invalid trees. */
+declare function validateDocsContent(input: unknown): {
+    content?: JSONContent;
+    diagnostics: DocsDiagnostic[];
+};
+declare function requireDocsContent(input: unknown): JSONContent;
+
+type PlainData = null | string | number | boolean | PlainData[] | {
+    [key: string]: PlainData;
+};
+type DocsFrontmatter = Record<string, PlainData>;
+/** DM-SOURCE: unknown metadata is retained as bounded, inert plain data. */
+declare function requireDocsFrontmatter(value: unknown, file?: string): DocsFrontmatter;
+declare function splitDocsFrontmatter(source: string, file?: string): {
+    frontmatter: DocsFrontmatter;
+    body: string;
+    lineOffset: number;
+};
+declare function serializeDocsFrontmatter(meta: DocsFrontmatter): string;
+
+declare const DOCS_PARSER_VERSION = 1;
+/** DM-CONVERT: CommonMark/GFM is parsed as data. Unsupported constructs fail closed. */
+declare function parseDocsMarkdown(markdown: string, options?: {
+    file?: string;
+    frontmatter?: boolean;
+}): {
+    content: JSONContent;
+    frontmatter: DocsFrontmatter;
+};
+declare function serializeDocsMarkdown(input: unknown, frontmatter?: DocsFrontmatter): string;
+
+/** DM-CONVERT: include conversion and retrieval versions in immutable content identities. */
+declare function hashDocsContent(input: {
+    content: unknown;
+    metadata: DocsFrontmatter;
+    embeddingConfigurationVersion: string;
+}): Promise<string>;
+
+/** DM-ROUTE: fixed /docs prefix, Latin segments, case-folded collision identity. */
+declare function normalizeDocsSlug(value: unknown): string;
+declare function normalizeDocsSourceDirectory(value: string): string;
+/** Input path is repository-relative; callers must also reject symlink entries in Git trees. */
+declare function resolveDocsSourcePath(path: string, directory: string, explicitSlug?: string): {
+    relativePath: string;
+    slug: string;
+    route: string;
+    sectionSlug: string;
+};
+
+export { DOCS_LIMITS, DOCS_PARSER_VERSION, DOCS_SCHEMA_VERSION, DocsContentError, type DocsDiagnostic, type DocsFrontmatter, type PlainData, createDocsExtensions, diagnostic, docsSchema, hashDocsContent, isSafeDocsUrl, normalizeDocsSlug, normalizeDocsSourceDirectory, parseDocsMarkdown, requireDocsContent, requireDocsFrontmatter, resolveDocsSourcePath, serializeDocsFrontmatter, serializeDocsMarkdown, sortDiagnostics, splitDocsFrontmatter, validateDocsContent };