@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/markdown-lite.d.ts

@@ -0,0 +1,297 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export type MarkdownInline = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'bold';
+    text: string;
+} | {
+    type: 'italic';
+    text: string;
+} | {
+    type: 'link';
+    text: string;
+    href: string;
+};
+/** A table cell's content. Cells hold inline runs only — no nesting. */
+export type MarkdownTableCell = MarkdownInline[];
+export type MarkdownTableAlign = 'left' | 'center' | 'right';
+export type MarkdownBlock = {
+    type: 'heading';
+    level: 2 | 3;
+    inlines: MarkdownInline[];
+} | {
+    type: 'paragraph';
+    inlines: MarkdownInline[];
+}
+/**
+ * A `> ` quote (AGL-1315) — the article template's pull-quote. Like a
+ * paragraph, one inline run: consecutive `> ` lines of a chunk join with
+ * spaces (a bare `>` continues the group and contributes nothing). The
+ * dialect has NO nesting — a second `>` is just text of the quote.
+ */
+ | {
+    type: 'quote';
+    inlines: MarkdownInline[];
+} | {
+    type: 'image';
+    src: string;
+    alt: string;
+} | {
+    type: 'list';
+    items: MarkdownInline[][];
+}
+/**
+ * A `1. ` / `1) ` numbered list (AGL-1320) — what a statute's enumerated
+ * elements need, and what `/legal/dmca` was flattening into run-on prose.
+ * `start` is the FIRST marker's number, so a notice continuing at `7.`
+ * keeps counting from seven; the rest renumber from it, which is how the
+ * serializer round-trips a `1. 1. 1.` source. A separate block rather than
+ * a flag on `list`, so the six renderers have to name it and no ordered
+ * list can silently render as bullets. NO nesting, like the rest of the
+ * dialect: indentation is trimmed, so a `  1. ` sub-item is a sibling.
+ */
+ | {
+    type: 'orderedList';
+    start: number;
+    items: MarkdownInline[][];
+}
+/** Fenced block. `text` is verbatim; `lang` is '' when none was given. */
+ | {
+    type: 'code';
+    lang: string;
+    text: string;
+}
+/**
+ * A GFM pipe table (AGL-974). Rectangular by construction: every row and
+ * `align` carry exactly `header.length` cells, so renderers never have to
+ * reason about ragged input and the serializer round-trips exactly.
+ */
+ | {
+    type: 'table';
+    align: MarkdownTableAlign[];
+    header: MarkdownTableCell[];
+    rows: MarkdownTableCell[][];
+};
+/**
+ * Whether a link target is one the parser will keep — the PUBLIC half of
+ * {@link safeLinkUrl}, so an editor can refuse what the parser would drop
+ * instead of discovering the disagreement on the published page (AGL-1686).
+ */
+export declare function isSupportedLinkHref(url: string): boolean;
+/**
+ * Whether an image source is one the parser will keep. The predicate an
+ * authoring surface must validate against, for the reason
+ * {@link isSupportedLinkHref} exists and one the editor learned the hard way:
+ * AGL-1645 widened the visual editor's image check to accept site-relative
+ * paths without widening this file, so every image picked from the media
+ * library serialized into the document and then vanished on the next parse.
+ * One predicate, two callers, no drift.
+ */
+export declare function isSupportedImageSrc(url: string): boolean;
+/**
+ * Whether a link target is a stored REFERENCE rather than an address
+ * (AGL-3118): a screen, a collection listing, an entry or a feed, named by id
+ * so a rename cannot break it. Only the marked, well-formed forms count — a
+ * bare id is indistinguishable from a relative path with no slash, so it
+ * stays what the dialect has always made of it.
+ *
+ * Kept verbatim in the parsed link: a renderer resolves it against the same
+ * routing map element links use, and the serializer writes it back as typed.
+ */
+export declare function isMarkdownLinkReference(url: string): boolean;
+/**
+ * True for hrefs the parser emitted as site-relative (start with `/`) AND that
+ * a client router can actually settle on.
+ *
+ * `/api/…` is excluded because those paths serve FILES, not pages —
+ * `/api/media/cdn/{scope}/{id}` is the download URL every media reference
+ * resolves to, and it is what "Browse media" hands an author who links a PDF
+ * or a logo kit. Routed through `AppLink` the click starts a client-side
+ * navigation that can never complete: the response is an attachment, so the
+ * router mounts its navigation-pending overlay and waits forever.
+ *
+ * The tell is a page trapped behind a spinner, NOT a failed download — the
+ * browser fetches the attachment underneath the overlay, so the file lands in
+ * Downloads while the site sits there looking broken. That mismatch sends you
+ * hunting the media endpoint, which answers `200` with a correct
+ * `Content-Disposition: attachment` every time.
+ *
+ * Both callers use this purely to choose `AppLink` vs a plain anchor, so
+ * narrowing it here fixes markdown bodies and collection item links together.
+ */
+export declare function isInternalMarkdownHref(href: string): boolean;
+/** How a renderer draws one parsed link — see {@link resolveMarkdownLink}. */
+export type MarkdownLinkResolution = 
+/** The link's text alone, with no anchor: a reference to a missing target. */
+{
+    kind: 'text';
+}
+/** Drawn as a link with nothing to follow, on an editing surface. */
+ | {
+    kind: 'inert';
+}
+/** A page of this site, for client-side navigation. */
+ | {
+    kind: 'internal';
+    href: string;
+}
+/** Anything else the parser kept, as a plain anchor. */
+ | {
+    kind: 'external';
+    href: string;
+};
+/**
+ * What one parsed link renders as (AGL-3118), for every markdown-lite
+ * renderer on a site: the Markdown element, the entry body and the legacy
+ * article surface.
+ *
+ * A link REFERENCE resolves against the routing map element links use, so a
+ * link in a post follows its target through a rename exactly as a button
+ * does, and a target the map does not have (unpublished, deleted, or never
+ * asked for) renders as the link's text — never as an anchor whose href is
+ * the stored reference. Every other href is the one the parser kept.
+ *
+ * An editing surface withholds every href, so there the only question is
+ * whether a link is drawn at all: a reference the map KNOWS is gone reads as
+ * the text the published page will show, and one the map cannot judge yet —
+ * nothing of its kind has loaded — keeps the link look, for the reason
+ * `isScreenLinkBroken` gives.
+ */
+export declare function resolveMarkdownLink(href: string, context?: {
+    screens?: Record<string, string> | null;
+    suppressNavigation?: boolean;
+}): MarkdownLinkResolution;
+export declare function parseMarkdownInlines(text: string): MarkdownInline[];
+/**
+ * Blocks are blank-line separated, EXCEPT inside a ``` fence — a code
+ * block owns its blank lines, so the scan is line-driven rather than a
+ * split on `\n{2,}` (AGL-974). An unterminated fence runs to the end of
+ * the document, which is what a README truncated mid-snippet needs.
+ */
+export declare function parseMarkdownLite(body: string): MarkdownBlock[];
+/**
+ * Markdown-lite SOURCE with its link references resolved (AGL-3118), for a
+ * reader that hands the source on instead of rendering it — the Markdown twin
+ * of a page, which an agent follows links out of.
+ *
+ * `resolve` answers a reference with the URL to write in its place, or with
+ * `undefined` for a target that is gone, and that link becomes its text
+ * alone: a reference no reader can follow is worse than no link at all. An
+ * image whose source is a reference becomes its alt text, because the parser
+ * draws no image for one.
+ *
+ * Everything else stays exactly as written, and fenced code is not touched —
+ * a reference quoted in a snippet is the snippet's text, as the parser has it.
+ */
+export declare function resolveMarkdownSourceLinks(source: string, resolve: (reference: string) => string | undefined): string;
+/**
+ * The plain text an inline run reads as — the words with the emphasis and
+ * link syntax removed. What a heading contributes to an anchor slug and to a
+ * table-of-contents label (AGL-1162), where `## The **fine** print` has to
+ * become "The fine print" and `the-fine-print`, not two of either.
+ */
+export declare function markdownInlinesToText(inlines: MarkdownInline[]): string;
+/** A heading a table of contents can point at (AGL-1162). */
+export interface MarkdownHeading {
+    level: 2 | 3;
+    /** Heading text with emphasis/link syntax stripped. */
+    text: string;
+    /** Anchor id, deterministic and unique within the document. */
+    slug: string;
+    /** Position in the block list, so a renderer can id the right heading. */
+    index: number;
+}
+/**
+ * Anchor id for one heading's text (AGL-1162).
+ *
+ * Deterministic by construction — the same words always produce the same id,
+ * which is the whole point: a legal page's true source is a markdown file
+ * elsewhere, and re-pasting it must not silently break every link that ever
+ * pointed into it. Accents fold to their base letter (NFKD then drop the
+ * combining marks) so `Résumé` and `Resume` are the same anchor rather than
+ * one of them being an unreadable percent-encoded id.
+ *
+ * A heading of nothing but punctuation or non-Latin script slugifies to
+ * empty; those get `SLUG_FALLBACK` here and are told apart by the numbering
+ * in {@link collectMarkdownHeadings}, because an id is required for the link
+ * to work at all and no id is worse than a dull one.
+ */
+export declare const SLUG_FALLBACK = "section";
+export declare function slugifyHeading(text: string): string;
+/**
+ * Every heading in a parsed document, with a unique anchor slug (AGL-1162).
+ *
+ * Duplicates take a `-2`, `-3`, … suffix in document order, and the loop
+ * re-checks the suffixed candidate: a document holding two `## Notice`
+ * headings AND a literal `## Notice 2` must not hand the same id to two
+ * elements, which is exactly what a plain counter would do.
+ *
+ * Deliberately NOT a widening of the `MarkdownBlock` union. The union is
+ * rendered exhaustively in six places, so a slug carried on the heading
+ * block would have to be produced by every writer of that union — including
+ * the visual editor's serializer, which round-trips through markdown source
+ * that has nowhere to put one. Derived here instead, from the same parse the
+ * renderer already has, so the markdown text stays the only source of truth.
+ */
+export declare function collectMarkdownHeadings(blocks: MarkdownBlock[]): MarkdownHeading[];
+/**
+ * The same headings keyed by block index, which is the shape every renderer
+ * actually wants (AGL-1162).
+ *
+ * A renderer maps over `blocks` and needs the slug for the block in hand;
+ * {@link collectMarkdownHeadings} returns a list, so each of them had to
+ * rebuild this map. There were six markdown renderers and one of them did —
+ * five published headings a table of contents could never link to, and the
+ * one that worked did it with a private `useMemo` nobody else could reach.
+ * Living here means a new renderer gets the numbering, the fallback and the
+ * duplicate-suffix rules for free rather than approximating them.
+ */
+export declare function markdownHeadingSlugs(blocks: MarkdownBlock[]): Record<number, string>;
+/**
+ * How far below a heading's anchor the viewport stops (AGL-1162) — enough to
+ * clear a sticky site header, so a `#slug` link does not land with the
+ * heading hidden underneath the nav. Shared so the published page, the entry
+ * body and the console preview all scroll to the same place.
+ */
+export declare const HEADING_ANCHOR_SCROLL_MARGIN = 96;
+/**
+ * Serializes inlines back to markdown-lite source (AGL-582). Characters an
+ * inline run cannot represent (the dialect has NO escapes) are dropped:
+ * `*` inside bold/italic, `]` in link text/alt, `)` or whitespace in URLs.
+ * Parser-emitted inlines never contain them, so for those this is exact.
+ */
+export declare function serializeMarkdownInlines(inlines: MarkdownInline[]): string;
+/**
+ * Inverse of `parseMarkdownLite` — the WYSIWYG round-trip contract
+ * (AGL-582): for any parser-produced model, the serialized string re-parses
+ * to a deep-equal model, and serializing is stable (a second
+ * parse→serialize round-trip returns the identical string). Editor-produced
+ * models are additionally NORMALIZED the same way the parser would: blocks
+ * and list items that would parse to nothing (empty text) are omitted, and
+ * block lines are edge-trimmed. Entry bodies stay markdown-lite strings in
+ * Firestore — this is the only writer the visual editor goes through.
+ *
+ * Every block is written as its own chunk, separated by a BLANK line, which
+ * is what holds the invariant now that a list may interrupt a paragraph
+ * (AGL-1320): `intro:` + `1. a` re-parses to the same paragraph + list pair
+ * whether or not the author left a blank line between them. The blank line is
+ * therefore load-bearing, not cosmetic: writing the two chunks adjacent would
+ * re-parse correctly today only by luck of the interrupt rule.
+ */
+export declare function serializeMarkdownLite(blocks: MarkdownBlock[]): string;