@wxxb789/anc 0.0.1

package/src/lib/preview-model.js

@@ -0,0 +1,96 @@
+/**
+ * The pure half of the hover preview: what may be shown, and where it goes.
+ *
+ * Split out of `src/scripts/link-preview.ts` for one reason — the placement
+ * arithmetic is the part most likely to be subtly wrong, and a browser test can
+ * only prove it for the link positions a corpus happens to contain. Nothing
+ * here touches the DOM, so every edge, every flip, and every malformed fragment
+ * is reachable from a unit test at `tests/preview-model.test.ts`.
+ *
+ * This module is imported into the browser bundle, so it keeps the same
+ * discipline as `route-path.ts`: no artifact import, no site map, nothing a
+ * reader would download and never use.
+ */
+export const PREVIEW_TITLE_LIMIT = 400;
+/** A bounded title plus its public aliases, all rendered as text. */
+export function previewTitle(entry) {
+    const text = entry.aliases === undefined || entry.aliases.length === 0
+        ? entry.title
+        : `${entry.title} (${entry.aliases.join(', ')})`;
+    return text.length <= PREVIEW_TITLE_LIMIT
+        ? text
+        : `${text.slice(0, PREVIEW_TITLE_LIMIT - 1)}…`;
+}
+/** Between the link and the panel, and between the panel and the viewport edge. */
+export const PREVIEW_GAP_PX = 8;
+export const VIEWPORT_MARGIN_PX = 8;
+/**
+ * How much of a `#heading` fragment the panel will show.
+ *
+ * A fragment is a heading slug this pipeline generated, so it is already short;
+ * the bound exists because nothing in the artifact contract constrains it and an
+ * unbounded string in a fixed-width panel is a layout defect waiting for one
+ * long heading.
+ */
+export const FRAGMENT_LIMIT = 80;
+/**
+ * The section a `/notes/<slug>/#heading` link points at, as the panel shows it.
+ *
+ * Shown **verbatim**, decoded and bounded, rather than turned back into prose.
+ * The payload carries a note's title and excerpt and nothing per-heading, so the
+ * heading's real text is not available here; de-slugging `reading-a-build-log`
+ * into something title-like would be a guess rendered in the shape of a fact.
+ * The fragment is what the address bar will show on arrival, so it is the one
+ * thing that is certainly true about the target.
+ *
+ * `decodeURIComponent` throws on a malformed escape, which a hand-written href
+ * can contain. That is a "fail silently" case, not a broken preview: the raw
+ * fragment is still an honest label.
+ */
+export function previewFragment(hash) {
+    const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+    if (raw === '')
+        return undefined;
+    let text;
+    try {
+        text = decodeURIComponent(raw);
+    }
+    catch {
+        text = raw;
+    }
+    return `#${text.length > FRAGMENT_LIMIT ? `${text.slice(0, FRAGMENT_LIMIT)}…` : text}`;
+}
+/**
+ * Keep a coordinate inside its bounds, with the low edge winning a tie.
+ *
+ * `lowest` is applied last deliberately. When the panel is larger than the
+ * space available, `highest` falls below `lowest` and one of the two edges has
+ * to be given up; giving up the far edge keeps the panel's top-left corner —
+ * where the title is, and where reading starts — on screen.
+ */
+function clamp(desired, lowest, highest) {
+    return Math.max(lowest, Math.min(desired, highest));
+}
+/**
+ * Where the panel goes, in viewport coordinates, for a link at `anchor`.
+ *
+ * Below the link by default, flipped above it when the panel does not fit below
+ * *and* there is more room above — the second condition matters, because a link
+ * near the top of a tall page has no room either way and flipping it there
+ * would trade a clipped bottom for a clipped top. Both coordinates are then
+ * clamped, so all four viewport edges hold whatever the link's position and the
+ * panel's size turn out to be.
+ *
+ * Viewport coordinates because the panel is `position: fixed`; that is the same
+ * space `getBoundingClientRect` reports in, so no scroll offset enters the
+ * arithmetic and there is nothing to keep in sync while the page scrolls.
+ */
+export function placePreview(anchor, panel, viewport) {
+    const roomBelow = viewport.height - VIEWPORT_MARGIN_PX - (anchor.bottom + PREVIEW_GAP_PX);
+    const roomAbove = anchor.top - PREVIEW_GAP_PX - VIEWPORT_MARGIN_PX;
+    const isAbove = panel.height > roomBelow && roomAbove > roomBelow;
+    return {
+        left: clamp(anchor.left, VIEWPORT_MARGIN_PX, viewport.width - VIEWPORT_MARGIN_PX - panel.width),
+        top: clamp(isAbove ? anchor.top - PREVIEW_GAP_PX - panel.height : anchor.bottom + PREVIEW_GAP_PX, VIEWPORT_MARGIN_PX, viewport.height - VIEWPORT_MARGIN_PX - panel.height),
+    };
+}

package/src/lib/relations.js

@@ -0,0 +1,242 @@
+/**
+ * Derived relationships: what a note is *near*, when nothing links it there.
+ *
+ * The artifact carries two authored edge sets — `outgoing` and `backlinks` —
+ * and `checkCorpus` proves they are exact inverses of each other. Everything in
+ * this module is the other kind of relationship: not an edge somebody wrote,
+ * but an adjacency computed from public metadata. The two must never be
+ * confused on the page, which is why they render under separate headings and
+ * why the derived list says on its face that it is derived.
+ *
+ * Pure, like `routes.ts`: nothing here imports the artifact. Callers pass the
+ * corpus in, so every rule below is exercisable against synthetic fixtures
+ * without building the site.
+ */
+import { byTitleThenSlug, collectionFacets, tagFacets } from "./routes.js";
+/**
+ * The shared title-then-slug comparator, owned by `routes.ts` and re-exported so
+ * this module's callers keep one import. It used to be restated here and held
+ * to agreement by a test; one definition makes the agreement structural.
+ */
+export { byTitleThenSlug };
+/**
+ * Resolve an edge list to the notes it names, in a stable reader order.
+ *
+ * Requirements section 13.1 asks for a stable sort order. The artifact stores
+ * both edge lists sorted by slug — which is what makes the corpus invariant
+ * cheap to check and is meaningless to a reader, since a slug is a URL segment
+ * and the reader is looking at titles. Sorting by title here is the display
+ * decision; the artifact's order is unchanged.
+ *
+ * An unresolvable slug is skipped rather than rendered as a dead link.
+ * `checkCorpus` already proves every edge resolves to a published entry, so
+ * this is unreachable through the validated loader — but this function is pure
+ * and fixture-driven, and a list of links must not depend on its caller having
+ * validated first.
+ */
+export function notesForSlugs(slugs, lookup) {
+    return slugs
+        .map(lookup)
+        .filter((entry) => entry !== undefined)
+        .sort(byTitleThenSlug);
+}
+/**
+ * How many related notes a page may list.
+ *
+ * Requirements section 9.2 item 10 requires the list to be bounded, and the
+ * number is chosen for the reader rather than for the data: a suggestion list
+ * longer than this stops being a suggestion and becomes a second index of the
+ * site, which the tag pages already are. Five also keeps the section inside one
+ * screen at 320 px.
+ */
+export const RELATED_LIMIT = 5;
+/**
+ * `tagFacets` for one corpus, computed once.
+ *
+ * Both functions below group the whole corpus by tag, and a static build calls
+ * them once per note — so without this the grouping runs twice per page, which
+ * measured **8.9 s** across a 900-entry corpus. With it, 224 ms.
+ *
+ * That 900 was `MAX_ENTRIES`, a ceiling this project no longer has: it refused
+ * an ordinary vault at 957 notes and `src/lib/schema.ts` records why it went.
+ * The measurement stands as a measurement *at 900 entries* and is no longer a
+ * measurement at the largest corpus this tool accepts — which is now unbounded,
+ * so the quadratic this cache removes matters more than it did, not less.
+ *
+ * That is a build-time cost only and nothing ships to a reader, but
+ * seconds of build for a value that cannot change between two calls in the same
+ * build is not a trade worth taking.
+ *
+ * A `WeakMap` keyed on the array a caller passed, rather than a module-level
+ * variable: the fixture build, the published build, and the tests all evaluate
+ * this module and pass *different* corpora, and a single cached value would
+ * serve one build's grouping to another. Keying on the array means a distinct
+ * corpus is a distinct entry, and a corpus nobody holds any more is collected.
+ * This module stays pure — the same input still gives the same answer.
+ */
+const facetsByCorpus = new WeakMap();
+function facetsFor(entries) {
+    const cached = facetsByCorpus.get(entries);
+    if (cached !== undefined)
+        return cached;
+    const computed = tagFacets(entries);
+    facetsByCorpus.set(entries, computed);
+    return computed;
+}
+/**
+ * The published tag groups this note belongs to.
+ *
+ * `facets` is the same index the tag routes render — the snapshot's own rows on
+ * the build path (`content.ts`), the producer normalization otherwise — so
+ * "shares a tag" here names exactly the pages the site publishes, and grouping
+ * never independently renormalizes what those pages show.
+ */
+function sharedFacets(entry, facets) {
+    return facets.filter((facet) => facet.entries.some((member) => member.slug === entry.slug));
+}
+/**
+ * Notes related to this one, most related first.
+ *
+ * **The rule.** A candidate is related when it shares at least one tag. It is
+ * ranked by its **rarest shared tag**: the tag that groups the fewest notes,
+ * with the smaller group ranking higher. Two candidates whose rarest shared tag
+ * is the same size are ordered by how many tags they share, then by a shared
+ * collection, then title, then slug.
+ *
+ * **Why the rarest tag rather than a sum of weights.** Summing per-tag rarity
+ * was the first version and it is not the rule anyone would state: two tags of
+ * 3 notes each outrank one tag of 2, so a candidate sharing several
+ * middle-frequency tags beats the one candidate sharing the tag that actually
+ * distinguishes this note. Taking the minimum makes the ranking say exactly
+ * what the page says it says — a claim in prose that the code does not
+ * implement is worse than a cruder rule.
+ *
+ * **Why rarity at all.** On the fixture corpus the tag `Field Notes` is on 20
+ * of 32 notes. Ranking by a plain count of shared tags makes "related" mean
+ * "also a note": measured on that corpus, `alias-heavy` and `undated-note-b`
+ * take 21 of the 89 top-three placements between them — a quarter of every
+ * suggestion on the site is one of two notes — because those two carry the two
+ * commonest tags and nothing else. A tag that groups three notes should count
+ * for more than one that groups two thirds of the site.
+ *
+ * **Why tags and not shared neighbours.** Shared neighbours were the other
+ * candidate in the ticket. They are already on the page: the two sections above
+ * this one render exactly the notes this one links to and is linked from, so a
+ * derivation over the same edges would mostly restate them. Tags are the only
+ * public grouping the artifact carries that the authored edges do not already
+ * express. Shared collection is kept, but as a tiebreak rather than as a source
+ * of candidates — a collection is coarse (three of them cover 28 of the 32
+ * fixture notes), so as a source it would list arbitrary collection members as
+ * "related".
+ *
+ * **What is excluded.** The note itself, and every note already named by
+ * `outgoing` or `backlinks`. Those render immediately above, and suggesting a
+ * page the reader can see two lines up is noise. That exclusion is what makes
+ * this a *fallback* list rather than a third edge list — and it is why the
+ * empty state must not claim nothing shares a tag: everything that does may
+ * simply be linked already. {@link hasTagPeer} answers that question so the
+ * page can say which of the two it is.
+ *
+ * Grouping comes from the facet index the caller passes — the snapshot's own
+ * tag rows on the build path, `content.ts`'s `tagFacets()`, and the producer
+ * normalization otherwise — rather than from a second pass over `entry.tags`,
+ * so "shares a tag" means exactly what "appears on the same tag page" means:
+ * `Gardening` and `gardening` are one tag here because they are one tag there.
+ * A private second normalization would let a note be listed as related on a tag
+ * the site never publishes.
+ *
+ * **The rule below is also stated to the reader, and that prose is not here.**
+ * It lives in `Translation.relatedDerivation`, in both languages, because it is
+ * chrome and chrome is per document since TK-16. It used to sit beside this
+ * comparator because the first version of this module shipped a page stating a
+ * rule the ranking did not implement — the prose said "rarest tag first" while
+ * the code summed weights, so two middling tags beat one rare one.
+ *
+ * So: **if you change the ranking below, change `relatedDerivation` in both
+ * locales of `src/lib/translations.ts`.** Proximity was never proof the two
+ * agreed — `tests/relations.test.ts` proves the rule and the gate over `dist/`
+ * asserts the page renders exactly the resolved sentence — but it was the
+ * reminder, and this paragraph is what replaces it.
+ *
+ * ponytail: `sharedFacets` still scans the whole index per call, so a build
+ * that asks for every note's related list is notes × tags. The `WeakMap` above
+ * removed the quadratic grouping, and the build path now also shares one index
+ * instead of rebuilding it. A per-note membership lookup would be the next
+ * step only if a corpus makes the remaining scan measurable.
+ */
+export function relatedNotes(entry, entries, facets = facetsFor(entries)) {
+    const excluded = new Set([entry.slug, ...entry.outgoing, ...entry.backlinks]);
+    const scored = new Map();
+    for (const facet of sharedFacets(entry, facets)) {
+        for (const candidate of facet.entries) {
+            if (excluded.has(candidate.slug))
+                continue;
+            const current = scored.get(candidate.slug);
+            if (current === undefined) {
+                scored.set(candidate.slug, { entry: candidate, rarest: facet.entries.length, shared: 1 });
+            }
+            else {
+                current.rarest = Math.min(current.rarest, facet.entries.length);
+                current.shared += 1;
+            }
+        }
+    }
+    const sharesCollection = (other) => entry.collection !== undefined && other.collection === entry.collection;
+    return [...scored.values()]
+        .sort((a, b) => {
+        if (a.rarest !== b.rarest)
+            return a.rarest - b.rarest;
+        if (a.shared !== b.shared)
+            return b.shared - a.shared;
+        const left = sharesCollection(a.entry);
+        const right = sharesCollection(b.entry);
+        if (left !== right)
+            return left ? -1 : 1;
+        return byTitleThenSlug(a.entry, b.entry);
+    })
+        .slice(0, RELATED_LIMIT)
+        .map((candidate) => candidate.entry);
+}
+/**
+ * Whether any other published note shares a tag with this one, linked or not.
+ *
+ * This is what separates the two reasons {@link relatedNotes} returns nothing.
+ * A note with no tag-sharer at all genuinely has no neighbourhood; a note whose
+ * every tag-sharer is already in `outgoing` or `backlinks` has one, and it is
+ * rendered in the two sections above. Saying "nothing shares a tag" in the
+ * second case would be a statement the artifact contradicts, which is exactly
+ * what the empty states exist to avoid.
+ */
+export function hasTagPeer(entry, entries, facets = facetsFor(entries)) {
+    return sharedFacets(entry, facets).some((facet) => facet.entries.some((member) => member.slug !== entry.slug));
+}
+/**
+ * The previous and next note in this note's collection.
+ *
+ * The sequence is {@link collectionFacets}' own order, which is the order
+ * `/collections/<key>/` lists them in — title, then slug. Any other order would
+ * put the pager and the collection index in disagreement, so a reader following
+ * "Next" repeatedly would walk the collection in an order its own index does
+ * not show. The artifact carries no authored sequence, so ordering by date
+ * would be inventing a reading order the owner never expressed, and `collection`
+ * is a flat slug with no nesting behind it — TK-05c owns hierarchy.
+ *
+ * A note with no collection, or the only note in one, has no sequence: both
+ * fields are absent and the page renders no pager. That is the "where
+ * meaningful" clause of requirements section 9.2 item 12 — a pager with two
+ * dead ends is chrome describing nothing.
+ */
+export function collectionNeighbours(entry, entries) {
+    if (entry.collection === undefined)
+        return {};
+    const facet = collectionFacets(entries).find((candidate) => candidate.key === entry.collection);
+    if (facet === undefined)
+        return {};
+    const at = facet.entries.findIndex((member) => member.slug === entry.slug);
+    if (at < 0)
+        return {};
+    return {
+        previous: at > 0 ? facet.entries[at - 1] : undefined,
+        next: at + 1 < facet.entries.length ? facet.entries[at + 1] : undefined,
+    };
+}

package/src/lib/rendered-marker.js

@@ -0,0 +1,55 @@
+/**
+ * The mark that says "a renderer produced this region", and nothing else.
+ *
+ * A leaf module with no imports, and that is the whole reason it exists rather
+ * than living beside the code that writes it. `scripts/scan-residue.ts` needs
+ * this vocabulary and its predicates, and importing them from
+ * `src/lib/markdown.ts` pulls in `mermaid-render.ts` and a top-level pass that
+ * loads every Prism grammar:
+ * measured, the residue scan went from **4.1 s to 25.5 s**, on a step that is a
+ * link of `pnpm run build` and of the shipped binary's chain. Every user's build
+ * would pay twenty seconds to read two literals.
+ *
+ * `src/lib/markdown.ts` documents what the mark *means*, where it is minted, and
+ * why that point is unforgeable. This file is the shared marker interface.
+ */
+/**
+ * The attribute a renderer's output carries.
+ *
+ * **Unbranded, deliberately.** A first version spelled this project's name into
+ * the attribute and `tests/site-identity.test.ts` went red on it: every stranger's note
+ * containing an expression or a diagram shipped this project's name into their
+ * own `dist/`, which is the headline TK-31 criterion. The attribute has to be
+ * unforgeable, not branded — and unforgeability comes from *where* it is
+ * written, not from what it is called.
+ */
+export const RENDERED_MARKER = 'data-rendered';
+/** The two kinds of region {@link RENDERED_MARKER} distinguishes. */
+export const RENDERED_MATH = 'math';
+export const RENDERED_DIAGRAM = 'diagram';
+/**
+ * The marker in an attribute position, wherever it occurs in an opening tag.
+ *
+ * Kept beside {@link MARKED_ROOT} so the residue scanner and script-budget gate
+ * cannot silently grow different definitions of the same security-sensitive
+ * grammar. The leading whitespace is load-bearing: without it, a marker-looking
+ * string inside another attribute's value would satisfy the predicate.
+ */
+export const MARKED_ATTRIBUTE = (kind) => new RegExp(`\\s${RENDERED_MARKER}="${kind}"`);
+/**
+ * A marked element's opening tag — the shape a consumer must look for.
+ *
+ * **Presence in the page is not the property either consumer wants.** The
+ * marker string has no character an HTML escaper rewrites, so a note body typing
+ * it in a paragraph puts it in the output as ordinary text — measured, and also
+ * through numeric character references such as
+ * `data-rendered="math"`. What no body can produce is
+ * the marker in an *attribute position on an element*, because it is written
+ * after the sanitizer.
+ *
+ * A first version of the script-budget gate tested the bare string against the
+ * whole page, so a note could mint itself 220 KB of allowance by typing it in
+ * prose — strictly worse than the author-writable class it replaced. This
+ * function exists so that mistake is not available by accident.
+ */
+export const MARKED_ROOT = (kind) => new RegExp(`<[a-zA-Z][a-zA-Z0-9-]*${MARKED_ATTRIBUTE(kind).source}`);

package/src/lib/route-path.js

@@ -0,0 +1,192 @@
+/**
+ * The note-route path shape, split out so a browser script can import it.
+ *
+ * `routes.ts` holds the site's navigation, its facet grouping, and its redirect
+ * map — none of which a client script needs. Importing it into one shipped a
+ * dead copy of the whole site map to every reader: Rolldown could not drop the
+ * `SITE_MAP` array literal, so it landed in the bundle as a no-op expression.
+ *
+ * This module is the part `link-preview.ts` actually needs, and nothing else.
+ * `routes.ts` re-exports from here, so the route shape is still defined once.
+ */
+/** The top-level segment notes live under. Reserved by TK-01's slug validation. */
+export const NOTES_SEGMENT = 'notes';
+/** The canonical route for a published note. */
+export function noteRoute(slug) {
+    return `/${NOTES_SEGMENT}/${slug}/`;
+}
+/**
+ * Where a link to a note this build did not publish points.
+ *
+ * A single page, identical for every withheld target, saying that the note is
+ * not published. It says nothing about *which* note — it cannot, because it is
+ * one static page — so the only thing a reader learns here is what the link they
+ * clicked already told them.
+ *
+ * **The segment is reserved, and that is not tidiness.** `markdown.ts`'s
+ * `INTERNAL_HREF` rewrites any single-segment `/<slug>/` href through
+ * `routeForSlug`, so without the reservation a user publishing a note named
+ * `private` would have every withheld link on their site silently redirected to
+ * *that note*. Measured against the regex: `/private/` matches it and
+ * `/notes/x/` does not. `src/lib/schema.ts` carries the reservation and
+ * `tests/route-model.test.ts` holds the pairing.
+ *
+ * Defined here rather than in `routes.ts` for the same reason {@link noteRoute}
+ * is: `scripts/resolve-links.ts` needs it while writing a body, and importing
+ * the site map into a traversal would tie the producer to the navigation.
+ */
+export const WITHHELD_ROUTE = '/private/';
+/**
+ * The accessible name a withheld link gets when the author wrote none.
+ *
+ * `[](note.md)` and `![](chart.png)` have no label at all, and under the rule
+ * this replaced they degraded to nothing, so the case did not arise. Now they
+ * become anchors, and an anchor with no text is one a screen reader announces as
+ * its URL and a pointer user cannot see. The resolved branch has had the same
+ * guard since TK-27, falling back to the target's slug; a withheld target has no
+ * slug to fall back to, so the fallback is what the destination says about
+ * itself.
+ *
+ * **Not resolved from `translations.ts`, and that is the same boundary
+ * `resolve-links.ts` already keeps.** This text is written into the author's
+ * *Markdown body*, which has one language — theirs — while chrome is resolved
+ * per document at render time. Threading a locale into the traversal would make
+ * the producer's output depend on a page's language, which is a different thing
+ * from the label a body carries. English matches `NAV_LANGUAGE`, the fallback
+ * every route that is not one document already renders.
+ */
+export const WITHHELD_LINK_TEXT = 'a note that is not published';
+/**
+ * The characters a note slug is made of: letters, numbers, and combining marks,
+ * in any script.
+ *
+ * One definition, shared with `routes.ts`'s tag route-key vocabulary (which adds
+ * `_`) and with `schema.ts`'s `isSlug`, so the producer, the contract, the
+ * renderer's href rewrite, the Worker's lookup guard, and the publish-set
+ * ledger cannot disagree about what a slug is. Kept in this browser-safe module
+ * because `link-preview.ts` parses a slug out of `location.pathname`.
+ *
+ * Underscore is deliberately **not** a slug character, unlike in a tag key: a
+ * slug is derived from a filename by replacing every run of anything else with
+ * one hyphen, so `first_note.md` becomes `first-note` and `first_note` is not a
+ * slug a producer could emit.
+ */
+export const SLUG_CHARACTERS = String.raw `\p{L}\p{N}\p{M}`;
+const SLUG_SHAPE = new RegExp(`^[${SLUG_CHARACTERS}]+(?:-[${SLUG_CHARACTERS}]+)*$`, 'u');
+/** At least one visible letter or digit; a slug of only combining marks is an invisible URL. */
+const SLUG_SUBSTANCE = /[\p{L}\p{N}]/u;
+/**
+ * Code points a renderer draws as nothing. U+FE0F is a nonspacing mark, so
+ * `\p{M}` alone would admit it; the rule is stated separately for that reason.
+ */
+export const INVISIBLE_CODE_POINTS = /\p{Default_Ignorable_Code_Point}/gu;
+const INVISIBLE_CODE_POINT = /\p{Default_Ignorable_Code_Point}/u;
+/**
+ * The longest slug, in **UTF-8 bytes**, not UTF-16 units.
+ *
+ * A slug is a directory name in the output (`notes/<slug>/index.html`), and the
+ * filesystems a site is built or served from cap a name at 255 bytes (ext4,
+ * APFS) or 255 UTF-16 units (NTFS). Counted in UTF-16 units, a 128-character CJK
+ * slug is 384 UTF-8 bytes and fails to write on Linux. 128 bytes is 128 ASCII
+ * characters or about 42 CJK characters, and its percent-encoded URL form is at
+ * most 384 characters.
+ */
+export const SLUG_MAX_BYTES = 128;
+const UTF8 = new TextEncoder();
+/** UTF-8 length, the unit {@link SLUG_MAX_BYTES} is stated in. */
+export function utf8Length(value) {
+    return UTF8.encode(value).length;
+}
+/**
+ * Whether a string is a canonical note slug.
+ *
+ * Lowercase (`toLowerCase` is the identity on it), NFC, free of invisible code
+ * points, hyphen-separated runs of {@link SLUG_CHARACTERS}, at least one letter
+ * or digit, and at most {@link SLUG_MAX_BYTES} bytes. The byte bound is part of
+ * the grammar rather than a separate limit so that a browser-side parse and the
+ * build agree on the same set.
+ */
+export function isNoteSlug(value) {
+    return (SLUG_SHAPE.test(value) &&
+        SLUG_SUBSTANCE.test(value) &&
+        !INVISIBLE_CODE_POINT.test(value) &&
+        value === value.normalize('NFC') &&
+        value === value.toLowerCase() &&
+        utf8Length(value) <= SLUG_MAX_BYTES);
+}
+/**
+ * One path segment (a folder or a filename stem) as slug text.
+ *
+ * NFC, Unicode lowercase, invisible code points removed, and every run of
+ * anything that is not a letter, number, or mark replaced with one hyphen,
+ * trimmed at both ends. `今天` stays `今天`, `Projects` becomes `projects`,
+ * `Three laws` becomes `three-laws`, and `___` or `🌱` becomes `''` — which
+ * the producer answers with a hash slug rather than inventing text.
+ */
+export function slugSegment(text) {
+    return text
+        .normalize('NFC')
+        .toLowerCase()
+        .normalize('NFC')
+        .replace(INVISIBLE_CODE_POINTS, '')
+        .replace(new RegExp(`[^${SLUG_CHARACTERS}]+`, 'gu'), '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * The canonical slug order: Unicode code point order.
+ *
+ * Not JavaScript's `<`, which compares UTF-16 code units and so sorts an astral
+ * character (`𠀀`, U+20000, stored as surrogates D840 DC00) *before* U+FF41.
+ * SQLite's `BINARY` collation compares UTF-8 bytes, which is code point order,
+ * and every `ORDER BY slug` and `slug > :after` cursor in the snapshot uses it.
+ * IDs are assigned in this order so that `ORDER BY id` and `ORDER BY slug`
+ * agree; the publish-set ledger and the artifact's edge lists use it too.
+ */
+export function compareSlugs(a, b) {
+    if (a === b)
+        return 0;
+    const left = a[Symbol.iterator]();
+    const right = b[Symbol.iterator]();
+    for (;;) {
+        const x = left.next();
+        const y = right.next();
+        if (x.done === true)
+            return y.done === true ? 0 : -1;
+        if (y.done === true)
+            return 1;
+        const difference = x.value.codePointAt(0) - y.value.codePointAt(0);
+        if (difference !== 0)
+            return difference < 0 ? -1 : 1;
+    }
+}
+/**
+ * The slug a single URL path segment names, or `undefined`.
+ *
+ * A browser presents `location.pathname` and `HTMLAnchorElement.pathname`
+ * percent-encoded (`/notes/%E4%BB%8A%E5%A4%A9/`), while a build-time href may
+ * carry the raw characters. Both are accepted: the segment is decoded (a
+ * malformed escape is not a slug), NFC-normalised, and then validated, so an
+ * encoded `/` or anything outside the grammar is refused.
+ */
+export function slugFromSegment(segment) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(segment);
+    }
+    catch {
+        return undefined;
+    }
+    const slug = decoded.normalize('NFC');
+    return isNoteSlug(slug) ? slug : undefined;
+}
+/**
+ * A path that only looks like a note route is not treated as one. The trailing
+ * slash is optional because a browser may present either form before the
+ * host's own normalization runs.
+ */
+const NOTE_PATH = new RegExp(`^/${NOTES_SEGMENT}/([^/]+)/?$`);
+/** The slug in a `/notes/<slug>/` path, raw or percent-encoded, or `undefined` for any other path. */
+export function noteSlugFromPath(pathname) {
+    const segment = NOTE_PATH.exec(pathname)?.[1];
+    return segment === undefined ? undefined : slugFromSegment(segment);
+}