@wxxb789/anc 0.0.1

package/src/lib/worker-protocol.js

@@ -0,0 +1,93 @@
+/**
+ * The lazy snapshot Worker's message contract.
+ *
+ * Pure and dependency-free so the Worker and the main-thread client import the
+ * same definition: a message the client can send is one the Worker can validate,
+ * and a result the Worker can return is one the client can type.
+ *
+ * The design constrains this shape (`docs/core-design/build-and-runtime.md`):
+ * messages carry a discriminated `type`, a request id, and operation-specific
+ * validated arguments. There is deliberately **no field that can carry SQL, a
+ * URL, a filesystem path, a table name, or a column name** — "named operations,
+ * not an SQL console" is structural here, not a convention enforced elsewhere.
+ */
+import { isLookupSlug, isLookupTagKey, normalizePageSize, } from "./snapshot-queries.js";
+/**
+ * Finite provisional bounds. Goal 0003 establishes these on the correctness
+ * fixtures; goal 0008 must validate or replace them on the benchmark workloads.
+ * They are not a capacity claim.
+ */
+export const WORKER_LIMITS = {
+    /** Fetch + hash + WASM init + schema validation. */
+    startupDeadlineMs: 20_000,
+    /** One dispatched request to a validated result. */
+    requestDeadlineMs: 8_000,
+    /** Concurrent requests before a new one is rejected rather than queued. */
+    maxPendingRequests: 16,
+    /** Decoded snapshot bytes read before WASM allocation. */
+    maxSnapshotBytes: 64 * 1024 * 1024,
+    /** Decoded WASM bytes read before instantiation. */
+    maxWasmBytes: 8 * 1024 * 1024,
+};
+export const SNAPSHOT_OPERATIONS = [
+    'preview',
+    'backlinks',
+    'outgoing',
+    'byTag',
+    'localGraph',
+    'globalGraph',
+];
+/**
+ * Whether an untrusted value is a request the Worker may run.
+ *
+ * Checks the discriminator, the id, and the lookup-shape of every argument.
+ * Page size and cursor are validated here too; `normalizePageSize` clamps rather
+ * than rejects, which is the accepted bound ("cap and validate the positive
+ * integer page size").
+ */
+export function isSnapshotMessage(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const message = value;
+    const id = message['id'];
+    if (typeof id !== 'number' || !Number.isInteger(id) || id <= 0)
+        return false;
+    const type = message['type'];
+    if (typeof type !== 'string' || !SNAPSHOT_OPERATIONS.includes(type))
+        return false;
+    // The instrumentation flag is optional, and only a boolean is a request the
+    // Worker may act on; any other value is refused rather than coerced. Checked
+    // before the per-operation branches because `preview`, `localGraph`, and
+    // `globalGraph` return from those branches, and an invalid flag must not slip
+    // past one of them. Unrelated extra keys stay ignored, as before.
+    const measure = message['measure'];
+    if (measure !== undefined && typeof measure !== 'boolean')
+        return false;
+    if (type === 'preview' || type === 'localGraph')
+        return isLookupSlug(message['slug']);
+    if (type === 'globalGraph') {
+        return message['tagKey'] === undefined || message['tagKey'] === null || isLookupTagKey(message['tagKey']);
+    }
+    if (type === 'byTag') {
+        if (!isLookupTagKey(message['tagKey']))
+            return false;
+    }
+    else if (!isLookupSlug(message['slug'])) {
+        return false;
+    }
+    const cursor = message['cursor'];
+    if (cursor !== undefined && cursor !== null && !isLookupSlug(cursor))
+        return false;
+    const pageSize = message['pageSize'];
+    if (pageSize !== undefined && typeof pageSize !== 'number')
+        return false;
+    return true;
+}
+/** The page size a validated request resolves to, clamped to the accepted range. */
+export function requestPageSize(message) {
+    return normalizePageSize(message['pageSize']);
+}
+/** Narrow a reply to the result type a caller asked for. */
+export function isResultOf(reply, type) {
+    return reply.ok && reply.result.type === type;
+}

package/src/pages/404.astro

@@ -0,0 +1,35 @@
+---
+/**
+ * Static 404.
+ *
+ * Astro emits `src/pages/404.astro` as `dist/404.html`, which Cloudflare Pages
+ * serves for any unmatched request. It is a real page in the layout shell, not
+ * a bare message: a reader who lands here still has the full site navigation.
+ *
+ * The routes offered are the site's own fixed routes. Nothing here reports what
+ * was requested — echoing the URL back into the page is how a 404 becomes a
+ * reflected-content sink, and it would tell a visitor nothing they did not type.
+ */
+import Layout from '../layouts/Layout.astro';
+import { SITE_MAP } from '../lib/routes.js';
+import { TITLE_SUFFIX } from '../lib/site.js';
+import { NAV_LANGUAGE, translate } from '../lib/translations.js';
+
+// The one route with no document behind it at all: the host serves this body
+// for any unmatched address, so there is nothing whose language could be read.
+const t = translate(NAV_LANGUAGE);
+---
+
+<Layout title={`${t.notFoundTitle}${TITLE_SUFFIX}`} description={t.notFoundDescription}>
+  <article class="prose">
+    <h1>{t.notFoundTitle}</h1>
+
+    <p>{t.notFoundBody}</p>
+
+    <h2>{t.notFoundWhereTo}</h2>
+
+    <ul>
+      {SITE_MAP.map((item) => <li><a href={item.href}>{t[item.label]}</a></li>)}
+    </ul>
+  </article>
+</Layout>

package/src/pages/about.astro

@@ -0,0 +1,100 @@
+---
+/**
+ * What this site is, for a reader who did not build it.
+ *
+ * **Rewritten by TK-31, because every substantive claim it made was false.**
+ * The previous version told a reader that "every page here is a note that was
+ * reviewed and explicitly approved for publication, one item at a time" and
+ * that a note "appears here only because it was named on an explicit approval
+ * list". That described the retired owner-specific bridge. This tool publishes a directory
+ * of Markdown by default and withholds what the user's `publish.config.yaml`
+ * excludes — the opposite arrangement — so the sentence a reader consults *to
+ * find out whether the boundary is trustworthy* was the sentence that lied
+ * about which direction it runs.
+ *
+ * **A shipped page rather than a Markdown note the user seeds.** The plan
+ * (§4.4) proposes deleting both prose pages and having `init` write them into
+ * the notes repository. That is the better end state and it is not reachable
+ * from here: `init` does not exist yet — it is TK-32's — and deleting the pages
+ * now would remove `/about/` and `/privacy/` from `SITE_MAP` and from three
+ * gates, leaving a build with no privacy statement at all in the interval. A
+ * page that is true is worth more than a page that is absent, and the sentences
+ * below are true of *every* build this tool produces rather than of one corpus.
+ *
+ * **So it says only what the tool guarantees.** Every claim here is a property
+ * of the generator — static output, no analytics, no third-party requests,
+ * exclusion by configuration — and none of it describes the user's own
+ * editorial process, which this repository cannot know and must not narrate on
+ * their behalf. Where the honest answer depends on the operator, it says so and
+ * points at them rather than inventing a policy.
+ *
+ * The prose is in the navigation language and is not translated, which is the
+ * same treatment `tests/translations.test.ts` records for this file: it is a
+ * document rather than chrome, and translating a document is a content decision
+ * this ticket does not own.
+ *
+ * **The withheld-link paragraph was rewritten on 2026-08-17** and it is the one
+ * claim here a reader could previously have been misled by. It said a link to an
+ * unpublished note "is not rendered as a link" and that "their content, their
+ * number, or that any exist" is not represented. Both became false when the
+ * owner made those links live: they are anchors now, they land on `/private/`,
+ * and a link's text is routinely the note's own path — so a reader can count
+ * them and read where they lived. The paragraph says that plainly, because a
+ * reader consulting this page to calibrate trust is exactly the person the
+ * omission would cost.
+ */
+import Layout from '../layouts/Layout.astro';
+import { DEFAULT_NAV_LANGUAGE } from '../lib/translations.js';
+import { SITE_NAME, TITLE_SUFFIX } from '../lib/site.js';
+---
+
+{/* The prose below is English whatever the site language, so the page says so. */}
+<Layout
+  title={`About${TITLE_SUFFIX}`}
+  lang={DEFAULT_NAV_LANGUAGE}
+  description="What this site is, and how its pages came to be here."
+>
+  <article class="prose">
+    <h1>About</h1>
+
+    <p>
+      {SITE_NAME} is a reading site. Each page is a note written in Markdown and published as a
+      static page, generated ahead of time rather than assembled when you ask for it.
+    </p>
+
+    <h2>How pages get here</h2>
+
+    <p>
+      The site is built from a set of notes written in Markdown. Publication is the default: a note
+      becomes a page unless it was explicitly excluded, and the person who runs the build chooses
+      what to exclude by listing patterns in a configuration file, or by marking an individual note.
+      An excluded note produces no page, no search entry, and none of its content appears here.
+    </p>
+
+    <p>
+      Links between notes are resolved when the site is built. A link whose target was not
+      published points at a page saying so, rather than at the note — so following one cannot
+      lead to something that is not here.
+    </p>
+
+    <p>
+      One thing this site does still show you about an unpublished note is the words a published
+      note used to refer to it. That link keeps its text exactly as the author wrote it, which
+      often means the note's own name and the path it had among the author's notes. It is the
+      author's writing rather than anything read from the note it names, and nothing else about
+      unpublished notes — their content, their titles, their number — is represented here.
+    </p>
+
+    <h2>How it is built</h2>
+
+    <p>
+      Every page is generated ahead of time and served as a static file. There is no server-side
+      application, no database behind a page view, and no account system. Reading, navigating,
+      following links, and browsing backlinks all work with JavaScript turned off.
+    </p>
+
+    <p>
+      For what this site does and does not collect, see <a href="/privacy/">Privacy</a>.
+    </p>
+  </article>
+</Layout>

package/src/pages/collections/[slug].astro

@@ -0,0 +1,36 @@
+---
+/**
+ * `/collections/<key>/` — the notes in one flat first-folder collection.
+ *
+ * A facet aggregates many documents, so its chrome is the navigation language
+ * rather than any member's; see `src/lib/translations.ts`. The collection name
+ * is artifact text, interpolated unchanged.
+ */
+import Layout from '../../layouts/Layout.astro';
+import NoteList from '../../components/NoteList.astro';
+import { entries } from '../../lib/content.js';
+import { collectionFacets } from '../../lib/routes.js';
+import { TITLE_SUFFIX } from '../../lib/site.js';
+import { NAV_LANGUAGE, translate } from '../../lib/translations.js';
+
+export function getStaticPaths() {
+  return collectionFacets(entries).map((facet) => ({ params: { slug: facet.key }, props: { facet } }));
+}
+
+const { facet } = Astro.props;
+const t = translate(NAV_LANGUAGE);
+---
+
+<Layout
+  title={`${t.collectionPageTitle(facet.label)}${TITLE_SUFFIX}`}
+  description={t.collectionPageDescription(facet.label)}
+>
+  <section aria-labelledby="collection-title">
+    <div class="section-heading">
+      <h1 id="collection-title">{t.collectionPageTitle(facet.label)}</h1>
+      <span>{t.noteCount(facet.entries.length)}</span>
+    </div>
+    <p class="facet-note"><a href="/collections/">{t.allCollections}</a></p>
+    <NoteList entries={facet.entries} level={2} lang={NAV_LANGUAGE} />
+  </section>
+</Layout>

package/src/pages/collections/index.astro

@@ -0,0 +1,33 @@
+---
+/**
+ * `/collections/` — the curated public collections.
+ *
+ * A corpus route, so the chrome is the navigation language. The collection
+ * labels are artifact text and are never translated.
+ */
+import Layout from '../../layouts/Layout.astro';
+import FacetIndex from '../../components/FacetIndex.astro';
+import { entries } from '../../lib/content.js';
+import { collectionFacets, collectionRoute } from '../../lib/routes.js';
+import { TITLE_SUFFIX } from '../../lib/site.js';
+import { NAV_LANGUAGE, translate } from '../../lib/translations.js';
+
+const t = translate(NAV_LANGUAGE);
+const facets = collectionFacets(entries);
+---
+
+<Layout title={`${t.collectionsTitle}${TITLE_SUFFIX}`} description={t.collectionsDescription}>
+  <section aria-labelledby="collections-title">
+    <div class="section-heading">
+      <h1 id="collections-title">{t.collectionsTitle}</h1>
+      <span>{t.collectionCount(facets.length)}</span>
+    </div>
+    <p class="facet-note">{t.collectionsNote}</p>
+    <FacetIndex
+      facets={facets}
+      route={collectionRoute}
+      empty={t.collectionsEmpty}
+      lang={NAV_LANGUAGE}
+    />
+  </section>
+</Layout>

package/src/pages/graph.astro

@@ -0,0 +1,64 @@
+---
+/**
+ * `/graph/` — the site-wide graph, requirements section 9.1's reserved route.
+ *
+ * A corpus route rather than a document route, so its chrome is the navigation
+ * language. The note titles it draws are their authors' own words and carry
+ * their own `lang`; `NoteGraph` handles that.
+ *
+ * Requirements section 13.3 admits a global graph only on four conditions, and
+ * this page meets them by construction rather than by intent:
+ *
+ * - *Legible at current node count* — `GLOBAL_NODE_LIMIT` bounds the figure, the
+ *   bound is stated on the page rather than applied silently, and the figure
+ *   scrolls below `min-width` rather than shrinking its labels past reading size.
+ * - *Keyboard-accessible, or an equivalent searchable list* — keyboard: every
+ *   node is a real `<a>` in the tab order, and the table under the figure lists
+ *   the same notes with the notes each is linked to. It is **not** in the site
+ *   search index: only `/notes/<slug>/` carries `data-pagefind-body`, so
+ *   Pagefind indexes note bodies alone. The requirement is satisfied by the
+ *   keyboard half, which is why that is the half this says.
+ * - *JS and database budgets* — there is no JavaScript and no database. TK-21
+ *   owns the layer that would have either, and it enhances this rather than
+ *   replacing it.
+ * - *Decision value beyond visual novelty* — the ranked packing puts the most
+ *   linked notes at the centre, so the figure answers "what is this site mostly
+ *   about" at a glance, and the table answers it exactly.
+ */
+import Layout from '../layouts/Layout.astro';
+import NoteGraph from '../components/NoteGraph.astro';
+import { entries, tagFacets } from '../lib/content.js';
+import { globalGraph, hasDrawableGraph } from '../lib/graph.js';
+import { TITLE_SUFFIX } from '../lib/site.js';
+import { NAV_LANGUAGE, translate } from '../lib/translations.js';
+// Loaded as a URL rather than imported, so the stylesheet becomes its own
+// content-hashed asset and the `<link>` below can be emitted conditionally —
+// owner decision 7. A page with nothing to draw requests nothing.
+import graphStylesheet from '../styles/graph.css?url';
+
+const t = translate(NAV_LANGUAGE);
+const graph = globalGraph(entries);
+---
+
+<Layout title={`${t.graphTitle}${TITLE_SUFFIX}`} description={t.graphDescription}>
+  {/* The same predicate the component branches on, so the stylesheet and the
+      figure can never disagree about whether there is a graph. */}
+  {hasDrawableGraph(graph) && <link slot="head" rel="stylesheet" href={graphStylesheet} />}
+
+  <NoteGraph
+    graph={graph}
+    region="site-graph"
+    level={1}
+    heading={t.graphTitle}
+    derivation={t.graphGlobalDerivation}
+    empty={t.graphSiteEmpty}
+    bounded={t.graphBounded}
+    expand={{ href: '/#notes', text: t.graphExpand, label: t.graphExpandLabel }}
+    lang={NAV_LANGUAGE}
+    explore={{
+      scope: 'global',
+      centerSlug: null,
+      tags: tagFacets().map((facet) => ({ key: facet.key, label: facet.label })),
+    }}
+  />
+</Layout>

package/src/pages/index.astro

@@ -0,0 +1,33 @@
+---
+/**
+ * The home page.
+ *
+ * Not one document but the whole corpus, so its chrome is the navigation
+ * language — see `src/lib/translations.ts` for the rule, and for why the
+ * alternative of borrowing some member's language would make a public page
+ * change language because an unrelated note was published.
+ */
+import Layout from '../layouts/Layout.astro';
+import NoteList from '../components/NoteList.astro';
+import { entries } from '../lib/content.js';
+import { SITE_NAME } from '../lib/site.js';
+import { NAV_LANGUAGE, translate } from '../lib/translations.js';
+
+const t = translate(NAV_LANGUAGE);
+---
+
+<Layout title={SITE_NAME} description={t.homeDescription}>
+  <section class="hero">
+    <p class="eyebrow">{t.homeEyebrow}</p>
+    <h1>{t.homeHeading}</h1>
+    <p>{t.homeIntro}</p>
+  </section>
+
+  <section id="notes" aria-labelledby="notes-title">
+    <div class="section-heading">
+      <h2 id="notes-title">{t.homeNotesHeading}</h2>
+      <span>{t.publishedCount(entries.length)}</span>
+    </div>
+    <NoteList entries={entries} lang={NAV_LANGUAGE} />
+  </section>
+</Layout>