@monoflake/sdk 0.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Canmi <t@canmi.icu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/dist/artifacts/src/anchors.d.ts

@@ -0,0 +1,34 @@
+import { Block } from "./types.js";
+//#region artifacts/src/anchors.d.ts
+/** The name each anchored block's anchors take: what a reader sees, not how it is drawn. */
+export declare const BLOCK_ANCHORS: {
+  readonly code: 'code';
+  readonly image: 'image';
+  readonly video: 'video';
+  readonly svgCanvas: 'diagram';
+  readonly mermaid: 'diagram';
+  readonly quadrant: 'chart';
+  readonly tokei: 'stats';
+  readonly cargo: 'crate';
+  readonly github: 'repo';
+  readonly twitter: 'tweet';
+  readonly linkcard: 'link';
+  readonly article: 'card';
+};
+/** Every name an anchor takes, once each. */
+export declare const ANCHOR_KINDS: ("card" | "chart" | "code" | "crate" | "diagram" | "image" | "link" | "repo" | "stats" | "tweet" | "video")[];
+/** A block anchor's kind and number, if `id` is one: `diagram-2`, not `code-review`. */
+export declare function parseBlockAnchor(id: string): {
+  kind: string;
+  number: number;
+} | undefined;
+/** Whether a heading's id would take a block anchor's place, which it may not. */
+export declare function isBlockAnchor(id: string): boolean;
+/** Each block's anchor, in order, or `undefined` for a block that takes none. */
+export declare function blockAnchors(blocks: readonly Pick<Block, 'type'>[]): (string | undefined)[];
+/**
+ * Where a block anchor that names nothing lands instead: the same kind's nearest number, the lower
+ * one on a tie, among `present`. Nothing when `id` is no block anchor or none of its kind exists.
+ */
+export declare function nearestBlockAnchor(id: string, present: readonly string[]): string | undefined;
+//#endregion

package/dist/artifacts/src/anchors.js

@@ -0,0 +1,64 @@
+//#region artifacts/src/anchors.ts
+/** The name each anchored block's anchors take: what a reader sees, not how it is drawn. */
+const BLOCK_ANCHORS = {
+	code: "code",
+	image: "image",
+	video: "video",
+	svgCanvas: "diagram",
+	mermaid: "diagram",
+	quadrant: "chart",
+	tokei: "stats",
+	cargo: "crate",
+	github: "repo",
+	twitter: "tweet",
+	linkcard: "link",
+	article: "card"
+};
+/** Every name an anchor takes, once each. */
+const ANCHOR_KINDS = [...new Set(Object.values(BLOCK_ANCHORS))];
+const ANCHOR = new RegExp(`^(${ANCHOR_KINDS.join("|")})-([1-9]\\d*)$`);
+/** A block anchor's kind and number, if `id` is one: `diagram-2`, not `code-review`. */
+function parseBlockAnchor(id) {
+	const found = ANCHOR.exec(id);
+	return found ? {
+		kind: found[1],
+		number: Number(found[2])
+	} : void 0;
+}
+/** Whether a heading's id would take a block anchor's place, which it may not. */
+function isBlockAnchor(id) {
+	return ANCHOR.test(id);
+}
+/** Each block's anchor, in order, or `undefined` for a block that takes none. */
+function blockAnchors(blocks) {
+	const counts = /* @__PURE__ */ new Map();
+	return blocks.map(({ type }) => {
+		const kind = BLOCK_ANCHORS[type];
+		if (!kind) return void 0;
+		const number = (counts.get(kind) ?? 0) + 1;
+		counts.set(kind, number);
+		return `${kind}-${number}`;
+	});
+}
+/**
+* Where a block anchor that names nothing lands instead: the same kind's nearest number, the lower
+* one on a tie, among `present`. Nothing when `id` is no block anchor or none of its kind exists.
+*/
+function nearestBlockAnchor(id, present) {
+	const asked = parseBlockAnchor(id);
+	if (!asked) return void 0;
+	let best;
+	for (const candidate of present) {
+		const found = parseBlockAnchor(candidate);
+		if (!found || found.kind !== asked.kind) continue;
+		const distance = Math.abs(found.number - asked.number);
+		if (!best || distance < best.distance || distance === best.distance && found.number < best.number) best = {
+			id: candidate,
+			distance,
+			number: found.number
+		};
+	}
+	return best?.id;
+}
+//#endregion
+export { ANCHOR_KINDS, BLOCK_ANCHORS, blockAnchors, isBlockAnchor, nearestBlockAnchor, parseBlockAnchor };

package/dist/artifacts/src/api.d.ts

@@ -0,0 +1,14 @@
+import * as v from "valibot";
+import { ApiError, ApiResponse, ApiSuccess, unwrap as unwrap$1 } from "@canmi/response";
+//#region artifacts/src/api.d.ts
+/**
+ * Open the envelope, then check that what was inside is what this call asked for.
+ *
+ * Two steps and one function, because every caller wants both and wanted them in that order. The
+ * envelope says whether the call worked; the schema says whether the payload is the shape the
+ * route promised. Kept here rather than in each consumer so that valibot stays this library's
+ * dependency and not everyone's. See spec/json.md.
+ */
+export declare function unwrapAs<S extends v.GenericSchema>(schema: S, body: unknown, source: string): v.InferOutput<S>;
+//#endregion
+export { type ApiError, type ApiResponse, type ApiSuccess, unwrap$1 as unwrap };

package/dist/artifacts/src/api.js

@@ -0,0 +1,20 @@
+import * as v from "valibot";
+import { unwrap, unwrap as unwrap$1 } from "@canmi/response";
+//#region artifacts/src/api.ts
+/**
+* The envelope lives in lib/pkgs/response, beside its Rust half; these are its re-exports for the
+* readers that already take their contracts from here.
+*/
+/**
+* Open the envelope, then check that what was inside is what this call asked for.
+*
+* Two steps and one function, because every caller wants both and wanted them in that order. The
+* envelope says whether the call worked; the schema says whether the payload is the shape the
+* route promised. Kept here rather than in each consumer so that valibot stays this library's
+* dependency and not everyone's. See spec/json.md.
+*/
+function unwrapAs(schema, body, source) {
+	return v.parse(schema, unwrap(body, source));
+}
+//#endregion
+export { unwrap$1 as unwrap, unwrapAs };

package/dist/artifacts/src/batch.d.ts

@@ -0,0 +1,105 @@
+import { Resource } from "./resource.js";
+import { ViewAnswer } from "./index.js";
+import * as v from "valibot";
+import { LocaleCode } from "@canmi/me/locales";
+//#region artifacts/src/batch.d.ts
+/**
+ * Several articles in several languages, as the cross product.
+ *
+ * One shape for two gestures: a language menu is one slug and many locales, a homepage warming
+ * its list is many slugs and one locale. They were two routes and are one question.
+ */
+export declare const ArticlesRequestSchema: v.ObjectSchema<{
+  readonly type: v.LiteralSchema<"articles", undefined>;
+  readonly slugs: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MaxLengthAction<string[], 64, undefined>]>;
+  readonly locales: v.SchemaWithPipe<readonly [v.ArraySchema<v.PicklistSchema<readonly ["mw", "de", "en", "es", "fr", "ja", "ko", "zh", "tw"], undefined>, undefined>, v.MaxLengthAction<("de" | "en" | "es" | "fr" | "ja" | "ko" | "mw" | "tw" | "zh")[], 9, undefined>]>;
+}, undefined>;
+/** How many times each of these articles has been read, without any of it counting as a read. */
+export declare const ReadsRequestSchema: v.ObjectSchema<{
+  readonly type: v.LiteralSchema<"reads", undefined>;
+  readonly slugs: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MaxLengthAction<string[], 64, undefined>]>;
+}, undefined>;
+/**
+ * How many resources one question carries.
+ *
+ * **A limit of the request and never of the page**, which is a difference a caller reading it the
+ * other way pays for with a blank article rather than a missing picture. `resourceQuestions` is
+ * that reading, written down so nobody has to arrive at it. See spec/architecture/resource.md,
+ * "One question per page". Measured: the heaviest article in this corpus names fifteen.
+ */
+export declare const RESOURCES_PER_QUESTION = 64;
+/**
+ * What every rid on one page currently means, asked once.
+ *
+ * An arm here rather than a fan of `GET /media?resource=`, and bounded like the slugs above: one
+ * page's worth, not a walk of the corpus. Unchecked against the id pattern for the reason `slugs`
+ * is -- a string that could never be one comes back absent, which is the same answer sooner. See
+ * spec/architecture/resource.md, "One question per page, not one per resource".
+ */
+export declare const ResourcesRequestSchema: v.ObjectSchema<{
+  readonly type: v.LiteralSchema<"resources", undefined>;
+  readonly resources: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MaxLengthAction<string[], 64, undefined>]>;
+}, undefined>;
+/**
+ * The questions one page's rids become: deduplicated, and split where the request shape ends.
+ *
+ * One list in and one question out, for every page this corpus has and every page it plausibly
+ * grows -- the split is the tail nobody reaches, and it exists so that reaching it costs a second
+ * request rather than the page. Deduplicated here as well as at the collector, because a caller
+ * can hand this a list assembled from more than one view.
+ */
+export declare function resourceQuestions(rids: readonly string[]): string[][];
+/**
+ * What arrives at `/batch`, discriminated by `type`.
+ *
+ * A variant rather than a union of objects: valibot reads `type` first and reports the failure
+ * against that one branch, so a malformed `reads` body is not also reported as a bad `articles`.
+ */
+export declare const BatchRequestSchema: v.VariantSchema<"type", [v.ObjectSchema<{
+  readonly type: v.LiteralSchema<"articles", undefined>;
+  readonly slugs: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MaxLengthAction<string[], 64, undefined>]>;
+  readonly locales: v.SchemaWithPipe<readonly [v.ArraySchema<v.PicklistSchema<readonly ["mw", "de", "en", "es", "fr", "ja", "ko", "zh", "tw"], undefined>, undefined>, v.MaxLengthAction<("de" | "en" | "es" | "fr" | "ja" | "ko" | "mw" | "tw" | "zh")[], 9, undefined>]>;
+}, undefined>, v.ObjectSchema<{
+  readonly type: v.LiteralSchema<"reads", undefined>;
+  readonly slugs: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MaxLengthAction<string[], 64, undefined>]>;
+}, undefined>, v.ObjectSchema<{
+  readonly type: v.LiteralSchema<"resources", undefined>;
+  readonly resources: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MaxLengthAction<string[], 64, undefined>]>;
+}, undefined>], undefined>;
+export type BatchRequest = v.InferOutput<typeof BatchRequestSchema>;
+export type BatchType = BatchRequest['type'];
+/**
+ * One article's views, named once each.
+ *
+ * `path` and `url` sit above the views rather than inside every one, which is the only reason this
+ * is not a list of `/article` answers. The slug is not in here at all: it is the key this article
+ * is filed under, and repeating it inside would be the same fact twice.
+ */
+export type BatchedArticle = {
+  path: string;
+  url: string;
+  views: Partial<Record<LocaleCode, Omit<ViewAnswer, 'slug' | 'path' | 'url'>>>;
+};
+/**
+ * What `/batch` answers, carrying back the `type` it was asked.
+ *
+ * Echoed rather than assumed: a consumer holding an answer can tell what it is an answer to
+ * without remembering what it sent. A slug or a rid the corpus does not name is absent rather
+ * than an error. Every map is keyed by what was asked with -- the identity, never the address --
+ * because an answer keyed by anything else could not be matched back to the question without the
+ * caller deriving one from the other.
+ */
+export type BatchAnswer = {
+  type: 'articles';
+  articles: Record<string, BatchedArticle>;
+} | {
+  type: 'reads';
+  reads: Record<string, number>;
+} | {
+  type: 'resources';
+  resources: Record<string, Resource>;
+};
+export type BatchAnswerOf<T extends BatchType> = Extract<BatchAnswer, {
+  type: T;
+}>;
+//#endregion

package/dist/artifacts/src/batch.js

@@ -0,0 +1,81 @@
+import * as v from "valibot";
+import { LOCALE_CODES } from "@canmi/me/locales";
+//#region artifacts/src/batch.ts
+/**
+* The one batch entry point, and what may be asked through it.
+*
+* A single lookup is a `GET` with its identifiers in the query; asking about many things is a
+* `POST` carrying a list, because a list does not belong in a URL. That left the API growing one
+* route per batchable question -- `/views`, `/read-counts` -- each a second spelling of a question
+* already answered singly, and each needing its own name.
+*
+* So there is one route, `POST /batch`, and the body says which question it is. `type` selects the
+* module that reads the rest; adding a batchable question adds a variant here and a handler there,
+* and no route at all. See spec/architecture/artifacts.md, "One batch entry point".
+*/
+/** A slug names an article; the list is bounded so one request cannot ask for the whole corpus. */
+const slugs = v.pipe(v.array(v.string()), v.maxLength(64));
+/**
+* Several articles in several languages, as the cross product.
+*
+* One shape for two gestures: a language menu is one slug and many locales, a homepage warming
+* its list is many slugs and one locale. They were two routes and are one question.
+*/
+const ArticlesRequestSchema = v.object({
+	type: v.literal("articles"),
+	slugs,
+	locales: v.pipe(v.array(v.picklist(LOCALE_CODES)), v.maxLength(LOCALE_CODES.length))
+});
+/** How many times each of these articles has been read, without any of it counting as a read. */
+const ReadsRequestSchema = v.object({
+	type: v.literal("reads"),
+	slugs
+});
+/**
+* How many resources one question carries.
+*
+* **A limit of the request and never of the page**, which is a difference a caller reading it the
+* other way pays for with a blank article rather than a missing picture. `resourceQuestions` is
+* that reading, written down so nobody has to arrive at it. See spec/architecture/resource.md,
+* "One question per page". Measured: the heaviest article in this corpus names fifteen.
+*/
+const RESOURCES_PER_QUESTION = 64;
+/**
+* What every rid on one page currently means, asked once.
+*
+* An arm here rather than a fan of `GET /media?resource=`, and bounded like the slugs above: one
+* page's worth, not a walk of the corpus. Unchecked against the id pattern for the reason `slugs`
+* is -- a string that could never be one comes back absent, which is the same answer sooner. See
+* spec/architecture/resource.md, "One question per page, not one per resource".
+*/
+const ResourcesRequestSchema = v.object({
+	type: v.literal("resources"),
+	resources: v.pipe(v.array(v.string()), v.maxLength(64))
+});
+/**
+* The questions one page's rids become: deduplicated, and split where the request shape ends.
+*
+* One list in and one question out, for every page this corpus has and every page it plausibly
+* grows -- the split is the tail nobody reaches, and it exists so that reaching it costs a second
+* request rather than the page. Deduplicated here as well as at the collector, because a caller
+* can hand this a list assembled from more than one view.
+*/
+function resourceQuestions(rids) {
+	const wanted = [...new Set(rids)];
+	const questions = [];
+	for (let from = 0; from < wanted.length; from += 64) questions.push(wanted.slice(from, from + 64));
+	return questions;
+}
+/**
+* What arrives at `/batch`, discriminated by `type`.
+*
+* A variant rather than a union of objects: valibot reads `type` first and reports the failure
+* against that one branch, so a malformed `reads` body is not also reported as a bad `articles`.
+*/
+const BatchRequestSchema = v.variant("type", [
+	ArticlesRequestSchema,
+	ReadsRequestSchema,
+	ResourcesRequestSchema
+]);
+//#endregion
+export { ArticlesRequestSchema, BatchRequestSchema, RESOURCES_PER_QUESTION, ReadsRequestSchema, ResourcesRequestSchema, resourceQuestions };

package/dist/artifacts/src/engagement.d.ts

@@ -0,0 +1,61 @@
+import * as v from "valibot";
+//#region artifacts/src/engagement.d.ts
+/**
+ * The two public counters, which belong to the site rather than to whoever is asking.
+ *
+ * Separate from `LikedAnswer` so that this one may be shared-cached and rendered on the server.
+ * See web's spec/engagement.md.
+ */
+export declare const StatsAnswerSchema: v.ObjectSchema<{
+  readonly subscriber_count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+  readonly like_count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>;
+/** Whether this visitor has liked. Per address, so never shared and never server-rendered. */
+export declare const LikedAnswerSchema: v.ObjectSchema<{
+  readonly liked: v.BooleanSchema<undefined>;
+}, undefined>;
+/** Read counts by slug, for every slug asked for that names an article. */
+export declare const ReadsAnswerSchema: v.ObjectSchema<{
+  readonly reads: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+}, undefined>;
+/**
+ * One article and its count, which is what both halves of the read counter answer.
+ *
+ * `GET /read` asks and `POST /read` records, and they share a shape because they answer the same
+ * question -- the `POST` differing only in that its figure includes the visit it just made. A
+ * second schema would be the same two fields under another name, and a consumer would have to
+ * know which one it was holding to read them. See web's spec/engagement.md.
+ */
+export declare const ReadAnswerSchema: v.ObjectSchema<{
+  readonly slug: v.StringSchema<undefined>;
+  readonly read_count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>;
+/** Taking or giving back a like. */
+export declare const LikeAnswerSchema: v.ObjectSchema<{
+  readonly liked: v.BooleanSchema<undefined>;
+  readonly like_count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>;
+/**
+ * Subscribing, which answers with the token only the first time.
+ *
+ * A second subscription to an address already held answers without one, so that asking twice
+ * never hands out a capability over an existing subscription. See web's spec/engagement.md.
+ */
+export declare const NewsletterAnswerSchema: v.ObjectSchema<{
+  readonly email: v.StringSchema<undefined>;
+  readonly cancel_token: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+  readonly subscriber_count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>;
+/** Cancelling. The count is absent when the answer is about a subscription that was not there. */
+export declare const CancelAnswerSchema: v.ObjectSchema<{
+  readonly cancelled: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+  readonly subscriber_count: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+}, undefined>;
+export type StatsAnswer = v.InferOutput<typeof StatsAnswerSchema>;
+export type LikedAnswer = v.InferOutput<typeof LikedAnswerSchema>;
+export type ReadsAnswer = v.InferOutput<typeof ReadsAnswerSchema>;
+export type ReadAnswer = v.InferOutput<typeof ReadAnswerSchema>;
+export type LikeAnswer = v.InferOutput<typeof LikeAnswerSchema>;
+export type NewsletterAnswer = v.InferOutput<typeof NewsletterAnswerSchema>;
+export type CancelAnswer = v.InferOutput<typeof CancelAnswerSchema>;
+//#endregion

package/dist/artifacts/src/engagement.js

@@ -0,0 +1,67 @@
+import * as v from "valibot";
+//#region artifacts/src/engagement.ts
+/**
+* What the engagement API answers, as schemas rather than as types.
+*
+* These are the answers a browser reads, and a browser is reading something it did not produce --
+* across a network, from a Worker deployed on its own schedule. A type says what should arrive; a
+* schema is the only thing that says what did. The corpus answers are checked by their envelope
+* instead, which is cheaper and is all a content-addressed object needs; nothing here is
+* content-addressed. See spec/architecture/artifacts.md, "Validation is heavy where it is free".
+*
+* Shared because both sides want the same sentence: the Worker builds an answer that satisfies
+* the inferred type, and the browser parses what arrives against the schema it was inferred from.
+*/
+/** A counter is a whole number and never negative, which is most of what can go wrong with one. */
+const counter = v.pipe(v.number(), v.integer(), v.minValue(0));
+/** A capability token as the API mints it: 128 bits, lowercase hex. */
+const cancelToken = v.pipe(v.string(), v.regex(/^[0-9a-f]{32}$/));
+/**
+* The two public counters, which belong to the site rather than to whoever is asking.
+*
+* Separate from `LikedAnswer` so that this one may be shared-cached and rendered on the server.
+* See web's spec/engagement.md.
+*/
+const StatsAnswerSchema = v.object({
+	subscriber_count: counter,
+	like_count: counter
+});
+/** Whether this visitor has liked. Per address, so never shared and never server-rendered. */
+const LikedAnswerSchema = v.object({ liked: v.boolean() });
+/** Read counts by slug, for every slug asked for that names an article. */
+const ReadsAnswerSchema = v.object({ reads: v.record(v.string(), counter) });
+/**
+* One article and its count, which is what both halves of the read counter answer.
+*
+* `GET /read` asks and `POST /read` records, and they share a shape because they answer the same
+* question -- the `POST` differing only in that its figure includes the visit it just made. A
+* second schema would be the same two fields under another name, and a consumer would have to
+* know which one it was holding to read them. See web's spec/engagement.md.
+*/
+const ReadAnswerSchema = v.object({
+	slug: v.string(),
+	read_count: counter
+});
+/** Taking or giving back a like. */
+const LikeAnswerSchema = v.object({
+	liked: v.boolean(),
+	like_count: counter
+});
+/**
+* Subscribing, which answers with the token only the first time.
+*
+* A second subscription to an address already held answers without one, so that asking twice
+* never hands out a capability over an existing subscription. See web's spec/engagement.md.
+*/
+const NewsletterAnswerSchema = v.object({
+	email: v.string(),
+	cancel_token: v.optional(cancelToken),
+	subscriber_count: counter
+});
+/** Cancelling. The count is absent when the answer is about a subscription that was not there. */
+const CancelAnswerSchema = v.object({
+	cancelled: v.optional(v.boolean()),
+	subscriber_count: v.optional(counter)
+});
+//#endregion
+export { CancelAnswerSchema, LikeAnswerSchema, LikedAnswerSchema, NewsletterAnswerSchema, ReadAnswerSchema, ReadsAnswerSchema, StatsAnswerSchema };

package/dist/artifacts/src/feed.d.ts

@@ -0,0 +1,42 @@
+import { Block } from "./types.js";
+import { LocaleCode } from "@canmi/me/locales";
+//#region artifacts/src/feed.d.ts
+/** Where the two absolute links a feed writes are rooted. */
+export type FeedBases = {
+  /** The site's own origin, for an `::article` card pointing at another article here. */
+  site: string;
+  /**
+   * Where a bare resource id is resolved, already ending in a slash.
+   *
+   * A feed cannot pick a width and has nothing to resolve a rid with, so it names the id
+   * itself and lets the alias layer answer with the largest rendition that resource declares.
+   * That is what `ill.li/{rid}` is for from outside, and it is stable across a re-encode in a
+   * way a baked address never was. See spec/architecture/resource.md, "A bare id means
+   * whatever the resource says it means".
+   */
+  resources: string;
+  /** The article's own URL, named by everything a feed cannot show in place. */
+  url: string;
+  /**
+   * The view this document is, written into every link that stays on the site.
+   *
+   * Spelled out even for `mw`, where the bare address would do on a page. A bare URL negotiates
+   * from the reader's cookie, and nothing in a feed will correct that afterwards -- so a card
+   * showing a Japanese title has to name the Japanese view, and one in the source feed has to
+   * name the source. See web's spec/locale/views.md.
+   */
+  locale: LocaleCode;
+};
+/** Exported because a feed body is not only blocks: see the site's translation notice. */
+export declare function escapeHtml(value: string): string;
+/**
+ * One block as feed HTML, or nothing where the feed has nothing to say.
+ *
+ * A pending embed is the only `nothing`, and it is the reason a placeholder carries `pending` at
+ * all: what it would say is that `local embed` has not run, which is a fact about this repository
+ * rather than about the article.
+ */
+export declare function blockFeedHtml(block: Block, bases: FeedBases): string | undefined;
+/** The whole body, one block to a line, in the order the article was written. */
+export declare function feedHtml(blocks: readonly Block[], bases: FeedBases): string;
+//#endregion

package/dist/artifacts/src/feed.js

@@ -0,0 +1,89 @@
+import { URLS } from "../../src/index.js";
+//#region artifacts/src/feed.ts
+/** Exported because a feed body is not only blocks: see the site's translation notice. */
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+/**
+* What a feed says about a drawing it cannot show.
+*
+* The title is the fence's own when it has one and the article's otherwise, which in this corpus
+* means the article's: no fence carries meta. So a described diagram says what it draws, and an
+* undescribed one says only that it is there, which is all it ever said.
+*/
+function diagram(title, description, url) {
+	return `<p><em>[Diagram: ${escapeHtml(description ?? title)} — view at ${url}]</em></p>`;
+}
+function region(item, axes) {
+	const [vertical, horizontal] = item.at.split("-");
+	return `${axes[vertical]} / ${axes[horizontal]}`;
+}
+/**
+* Name the view on every link that stays on this site.
+*
+* Prose is the page's own HTML, and a page links the bare address because its router carries the
+* view across. A feed has no router, so a bare link resolves against whatever the reader's cookie
+* holds. Left alone: an outside address, a bare fragment, and one that already names a language.
+* See web's spec/locale/views.md.
+*/
+function pinView(html, { site, locale }) {
+	return html.replaceAll(/href="([^"]*)"/g, (whole, href) => {
+		if (!(href.startsWith(`${site}/`) || href === site || href.startsWith("/")) || /[?&]lang=/.test(href)) return whole;
+		const hash = href.indexOf("#");
+		const address = hash === -1 ? href : href.slice(0, hash);
+		const fragment = hash === -1 ? "" : href.slice(hash);
+		return `href="${address}${address.includes("?") ? "&" : "?"}lang=${locale}${fragment}"`;
+	});
+}
+/**
+* One block as feed HTML, or nothing where the feed has nothing to say.
+*
+* A pending embed is the only `nothing`, and it is the reason a placeholder carries `pending` at
+* all: what it would say is that `local embed` has not run, which is a fact about this repository
+* rather than about the article.
+*/
+function blockFeedHtml(block, bases) {
+	switch (block.type) {
+		case "prose": return pinView(block.html, bases);
+		case "heading": {
+			const marks = (block.notes ?? []).map((number) => `<sup>${number}</sup>`).join("");
+			return `<h${block.depth} id="${block.slug}">${escapeHtml(block.text)}${marks}</h${block.depth}>`;
+		}
+		case "code": return `<pre><code>${escapeHtml(block.code)}</code></pre>`;
+		case "mermaid": return block.description ? diagram("diagram", block.description, bases.url) : `<pre><code class="language-mermaid">${escapeHtml(block.source)}</code></pre>`;
+		case "tokei": return `<pre>${escapeHtml(block.source)}</pre>`;
+		case "svgCanvas": return diagram(block.title, block.description, bases.url);
+		case "quadrant": {
+			const entries = block.items.map((item) => {
+				const note = item.note ? ` — ${escapeHtml(item.note)}` : "";
+				return `<li><strong>${escapeHtml(item.title)}</strong>${note} <small>(${escapeHtml(region(item, block.axes))})</small></li>`;
+			});
+			const caption = block.description ? ` — ${escapeHtml(block.description)}` : "";
+			return `<figure><figcaption><strong>${escapeHtml(block.title)}</strong>${caption}</figcaption><ul>${entries.join("")}</ul></figure>`;
+		}
+		case "linkcard": return `<p><a href="${block.url}">${escapeHtml(block.title)}</a></p>`;
+		case "article": return `<p><a href="${bases.site}/${block.path}?lang=${bases.locale}">${escapeHtml(block.title)}</a> — ${escapeHtml(block.subtitle)}</p>`;
+		case "image": return `<p><img src="${bases.resources}${block.resources.picture}" alt="${escapeHtml(block.alt)}" /></p>`;
+		case "video": return `<p>${block.poster ? `<img src="${block.poster}" alt="${escapeHtml(block.description ?? "")}" /> ` : ""}<em>[Video — watch at ${bases.url}]</em></p>`;
+		case "cargo": return `<p><em>[crate: ${escapeHtml(block.crate.name)} ${escapeHtml(block.crate.version)}]</em></p>`;
+		case "github": return `<p><em>[repository: ${escapeHtml(block.repo.full_name)}]</em></p>`;
+		case "twitter": {
+			const { tweet } = block;
+			const href = `${URLS.external.social.twitter}/${tweet.author}/status/${tweet.id}`;
+			return `<blockquote><p>${escapeHtml(tweet.text).replaceAll("\n", "<br />")}</p><footer><a href="${href}">@${escapeHtml(tweet.author)} on Twitter</a></footer></blockquote>`;
+		}
+		case "footnotes": return `<ol>${block.notes.map(({ number, phrase, text }) => `<li id="note-${number}"><strong>${escapeHtml(phrase)}</strong> ${escapeHtml(text)}</li>`).join("")}</ol>`;
+		case "placeholder": return block.pending ? void 0 : `<pre>::${escapeHtml(block.kind)}${Object.entries(block.meta).map(([key, value]) => `\n${key} = "${escapeHtml(value)}"`).join("")}</pre>`;
+	}
+}
+/** The whole body, one block to a line, in the order the article was written. */
+function feedHtml(blocks, bases) {
+	const lines = [];
+	for (const block of blocks) {
+		const html = blockFeedHtml(block, bases);
+		if (html !== void 0) lines.push(html);
+	}
+	return lines.join("\n");
+}
+//#endregion
+export { blockFeedHtml, escapeHtml, feedHtml };