@monoflake/sdk 0.0.0

package/dist/artifacts/src/index.js

@@ -0,0 +1,219 @@
+import { HASH_PATTERN, byLocale, hash } from "./schema.js";
+import { unwrap, unwrapAs } from "./api.js";
+import { blockFeedHtml, escapeHtml, feedHtml } from "./feed.js";
+import { CancelAnswerSchema, LikeAnswerSchema, LikedAnswerSchema, NewsletterAnswerSchema, ReadAnswerSchema, ReadsAnswerSchema, StatsAnswerSchema } from "./engagement.js";
+import { ArticlesRequestSchema, BatchRequestSchema, RESOURCES_PER_QUESTION, ReadsRequestSchema, ResourcesRequestSchema, resourceQuestions } from "./batch.js";
+import { ArticleLayerSchema, CANONICAL_PATTERN, ClipLayerSchema, DocumentLayerSchema, FrameLayerSchema, IconLayerSchema, ImageLayerSchema, ImageVariantSchema, LAYERS, MarkLayerSchema, MediaLayerSchema, NoticeLayerSchema, PhotoLayerSchema, RESOURCE_PATTERN, RESOURCE_VERSION, ResourceSchema, SCALABLE_MIMES, ScreenshotLayerSchema, TONES, VideoLayerSchema, expandCanonical, isLayerName, isResourceId, parseResource, parseType, requireSegment } from "./resource.js";
+import { ICON_EXTENSION, VARIANT_EXTENSION, aspect, best, enough, height, namedResources, objectUrl, pictured, resolution, rungs, scalable, toned, width } from "./picture.js";
+import * as v from "valibot";
+import { LOCALE_CODES } from "@canmi/me/locales";
+//#region artifacts/src/index.ts
+/**
+* The shape every published object declares.
+*
+* Bumped when a producer and a consumer can no longer read each other. They deploy separately
+* now, so this is the only thing that tells a Worker it is holding bytes it does not understand.
+*/
+const ARTIFACT_VERSION = 2;
+const ARTIFACT_TYPES = [
+	"content",
+	"page",
+	"markdown"
+];
+/** What each corpus artifact is spelled with, in the address and in the bucket alike. */
+const ARTIFACT_EXTENSIONS = {
+	content: "json",
+	page: "json",
+	markdown: "md"
+};
+const EXTENSION = ARTIFACT_EXTENSIONS;
+/** The one object in the bucket whose name outlives its bytes. */
+const ROOT_KEY = "state/index.json";
+/**
+* The address a published object is served at.
+*
+* `object/{hash}.{ext}` -- not where it is stored, and no longer naming what kind of thing it is
+* either. The type survives as the one thing that decides the extension: a caller asks for a
+* `content` object and the table below says that is spelled `json`.
+*/
+function artifactAddress(type, hash) {
+	return `object/${hash}.${EXTENSION[type]}`;
+}
+/**
+* Where an object lives: its content id, fanned out, and nothing else.
+*
+* **The bucket's layout is not the CDN's URL.** A URL says `/object/{cid}.{ext}`; the bucket stores
+* `{ab}/{cd}/{cid}.{ext}`, because the id already identifies it and a type directory would be a
+* second place to write the same fact. The fan-out is for listing, and the extension is kept so a
+* bucket downloaded whole is still files that open. See web's spec/architecture/data.md, "The
+* bucket stores content ids, and so does the address".
+*/
+function storageKey(cid, extension) {
+	return `${cid.slice(0, 2)}/${cid.slice(2, 4)}/${cid}.${extension}`;
+}
+/**
+* Where a resource's record lives, which is in the other bucket entirely.
+*
+* **Keyed by the rid and never by a cid.** A key ending in a hash reads as content-addressed,
+* and the cache policy read the shape and granted a year -- to a record rewritten whenever its
+* asset is re-derived. That is the confusion spec/architecture/resource.md exists to end. See
+* also web's spec/architecture/data.md, "One bucket holds records and the other holds bytes".
+*/
+function recordKey(resource) {
+	return `meta/${resource}.json`;
+}
+/**
+* The classifier the cache policy is derived from, rather than a table of key prefixes.
+*
+* A key that parses is content-addressed and may be held forever; one that does not is not, and
+* gets the short life. That is the whole rule, so a new type costs no cache decision.
+*/
+function parseArtifactKey(key) {
+	const match = /^([a-z]+)\/([0-9a-f]+)\.([a-z0-9]+)$/.exec(key);
+	if (!match) return void 0;
+	const [, type, hash, ext] = match;
+	if (!type || !hash || !ext) return void 0;
+	if (!HASH_PATTERN.test(hash)) return void 0;
+	if (!ARTIFACT_TYPES.includes(type)) return void 0;
+	if (EXTENSION[type] !== ext) return void 0;
+	return {
+		type,
+		hash,
+		ext
+	};
+}
+/**
+* What an article says it is: the copy a page renders in its own right.
+*
+* `short` is the pair a phone card shows where the row clips, and it is a pair rather than two
+* keys because it is one decision -- see web's spec/i18n/prose.md.
+*/
+const ViewMetaSchema = v.object({
+	title: v.string(),
+	subtitle: v.string(),
+	description: v.string(),
+	short: v.object({
+		title: v.string(),
+		subtitle: v.string()
+	})
+});
+/**
+* One locale's view, grouped by what each group answers rather than laid out flat.
+*
+* Flat, this was thirteen keys where `title` sat beside `content` and `words` beside
+* `language_tag`, and a reader had to know the whole list to find anything. Each group below
+* answers one question: which objects carry it, which language it is, what it says, when it was
+* written, how big it is, and what a listing shows of it.
+*/
+const RootViewSchema = v.object({
+	objects: v.object({
+		content: hash,
+		card: v.optional(hash)
+	}),
+	locale: v.object({
+		language_tag: v.string(),
+		canonical: v.string(),
+		/** False when this locale is showing the source article as a safe fallback. */
+		translated: v.boolean()
+	}),
+	meta: ViewMetaSchema,
+	/**
+	* When the file came into being, when the article went public, and when it last changed.
+	* `published` is the author's to edit and the one a reader is shown.
+	*
+	* **A `v.object` drops a key it does not declare rather than refusing it**, so a producer
+	* that writes a fourth date without adding it here hands every consumer `undefined` and
+	* nothing reports it. `index.test.ts` pins this key set for that reason.
+	*/
+	dates: v.object({
+		created: v.string(),
+		published: v.string(),
+		lastmod: v.string()
+	}),
+	metrics: v.object({ words: v.number() }),
+	preview: v.object({ paragraphs: v.array(v.string()) })
+});
+/**
+* The codes an alternate may carry, which are narrower than the locales.
+*
+* `mw` is the source and is never an alternate of itself; `x-default` is the bare URL. Parsed as
+* the picklist rather than as a string so the root validates into `Alternate` -- the type every
+* consumer of these already assumes, and which a looser parse let the root quietly contradict.
+*/
+const alternateCode = v.picklist([...LOCALE_CODES.filter((code) => code !== "mw"), "x-default"]);
+const RootArticleSchema = v.object({
+	/** The identity: unique across the corpus, and what every question asks with. */
+	slug: v.string(),
+	/** The address: where it currently lives, which is the only half that can change. */
+	path: v.string(),
+	url: v.string(),
+	markdown: hash,
+	alternates: v.array(v.object({
+		code: alternateCode,
+		language_tag: v.string(),
+		href: v.string()
+	})),
+	canonical_urls: v.array(v.string()),
+	views: byLocale(RootViewSchema)
+});
+/**
+* A fixed name, and the object it currently means.
+*
+* The site's own marks -- its icons, its BIMI mark -- are published like anything else, addressed
+* by their content and cached for a year. What a reader or a mail client asks for is the name, so
+* something has to turn one into the other, and this is what it reads. See
+* spec/architecture/delivery.md, "A name is resolved, never stored".
+*/
+const RootAssetSchema = v.object({
+	cid: hash,
+	extension: v.string()
+});
+const RootSchema = v.object({
+	version: v.literal(2),
+	generated: v.string(),
+	/** Fixed names the alias layer resolves, keyed by the name as it is asked for. */
+	assets: v.record(v.string(), RootAssetSchema),
+	articles: v.array(RootArticleSchema),
+	pages: v.record(v.string(), v.object({
+		markdown: hash,
+		views: byLocale(v.object({
+			content: hash,
+			card: v.optional(hash)
+		}))
+	}))
+});
+/**
+* What a consumer checks before trusting an object's body.
+*
+* Version, slug and locale only -- the slug being the identity, never the path, because an object
+* outlives the directory it was published from. The body is not revalidated at an edge: the
+* producer is trusted and what this catches is version skew. See spec/architecture/artifacts.md,
+* "Validation is heavy where it is free and light where it is not".
+*/
+const EnvelopeSchema = v.object({
+	version: v.literal(2),
+	slug: v.string(),
+	locale: v.picklist(LOCALE_CODES)
+});
+/**
+* The same check for a page, which has no locale to check.
+*
+* A page is compiled once and filed under every locale -- see the builder, and web's
+* spec/i18n/copy.md for why identity copy is not translated. Giving its envelope a locale made nine
+* objects that differed in one field, which is de-duplication defeated by a field that meant
+* nothing.
+*/
+const PageEnvelopeSchema = v.object({
+	version: v.literal(2),
+	slug: v.string()
+});
+function readPageEnvelope(value, slug) {
+	const envelope = v.parse(PageEnvelopeSchema, value);
+	if (envelope.slug !== slug) throw new Error(`page artifact is ${envelope.slug}, asked for ${slug}`);
+}
+function readEnvelope(value, slug, locale) {
+	const envelope = v.parse(EnvelopeSchema, value);
+	if (envelope.slug !== slug || envelope.locale !== locale) throw new Error(`artifact is ${envelope.slug}/${envelope.locale}, asked for ${slug}/${locale}`);
+}
+//#endregion
+export { ARTIFACT_EXTENSIONS, ARTIFACT_TYPES, ARTIFACT_VERSION, ArticleLayerSchema, ArticlesRequestSchema, BatchRequestSchema, CANONICAL_PATTERN, CancelAnswerSchema, ClipLayerSchema, DocumentLayerSchema, EnvelopeSchema, FrameLayerSchema, HASH_PATTERN, ICON_EXTENSION, IconLayerSchema, ImageLayerSchema, ImageVariantSchema, LAYERS, LikeAnswerSchema, LikedAnswerSchema, MarkLayerSchema, MediaLayerSchema, NewsletterAnswerSchema, NoticeLayerSchema, PageEnvelopeSchema, PhotoLayerSchema, RESOURCES_PER_QUESTION, RESOURCE_PATTERN, RESOURCE_VERSION, ROOT_KEY, ReadAnswerSchema, ReadsAnswerSchema, ReadsRequestSchema, ResourceSchema, ResourcesRequestSchema, RootArticleSchema, RootAssetSchema, RootSchema, RootViewSchema, SCALABLE_MIMES, ScreenshotLayerSchema, StatsAnswerSchema, TONES, VARIANT_EXTENSION, VideoLayerSchema, ViewMetaSchema, artifactAddress, aspect, best, blockFeedHtml, enough, escapeHtml, expandCanonical, feedHtml, height, isLayerName, isResourceId, namedResources, objectUrl, parseArtifactKey, parseResource, parseType, pictured, readEnvelope, readPageEnvelope, recordKey, requireSegment, resolution, resourceQuestions, rungs, scalable, storageKey, toned, unwrap, unwrapAs, width };

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

@@ -0,0 +1,116 @@
+import { Block } from "./types.js";
+import { IconLayer, ImageLayer, ImageVariant, ParsedResource, Tone } from "./resource.js";
+//#region artifacts/src/picture.d.ts
+/** Step one: the intrinsic box, which every picture has. No branch and no decision. */
+export declare function width(image: ImageLayer): number;
+export declare function height(image: ImageLayer): number;
+export declare function aspect(image: ImageLayer): string;
+/** Step three: actual pixels, and `null` for a vector, which has none to report. */
+export declare function resolution(image: ImageLayer): {
+  width: number;
+  height: number;
+} | null;
+/**
+ * Whether this picture serves any size, which is the one place that knows which mimes scale.
+ *
+ * Asked of the variants because that is where a concrete mime is a fact; an absent `resolution`
+ * says the same thing and covers a layer whose variants have not been derived yet.
+ */
+export declare function scalable(image: ImageLayer): boolean;
+/**
+ * Step two, and the point of the other three: whether this can serve a target long edge.
+ *
+ * **The branch lives here.** A caller drawing a thumbnail never gets further than this line and
+ * never learns that formats exist, which is what keeps `scalable` from being a condition repeated
+ * in every caller. See spec/architecture/resource.md, "The image layer answers in four steps".
+ */
+export declare function enough(image: ImageLayer, want: number): boolean;
+/**
+ * Step four: the file to serve for a target long edge.
+ *
+ * The smallest rung that covers the target, because anything larger is weight a reader pays for and
+ * nobody sees; the largest when none of them does, since upscaling is never done and the top rung
+ * is the best answer that exists. See web's spec/architecture/media.md, "Variants stop where the
+ * layout does".
+ */
+export declare function best(image: ImageLayer, want: number): ImageVariant | undefined;
+/**
+ * What an icon's file is spelled with, keyed by what is in it.
+ *
+ * Its own table rather than the variant one, for the reason `for_icon` is its own on the other
+ * side: these bytes were encoded by somebody else's server and arrive as SVG or ICO, neither of
+ * which a ladder ever produces -- and the ladder's table answers `avif` for anything it does not
+ * recognise, which would be an address to a file nobody wrote. The twin of `icon_mime` in
+ * services/apps/local/src/extension.rs, held to it by a test here.
+ */
+export declare const ICON_EXTENSION: Record<string, string>;
+/**
+ * Which of an icon's files answers for a tone, and `undefined` when none does.
+ *
+ * A named tone is that tone or nothing: a caller handed the other one cannot tell it happened,
+ * and would draw a light mark on a dark surface believing it had the right one. With none named
+ * either will do, light first, an untinted mark being drawn for light backgrounds. The one place
+ * that rule is written on this side, having been the alias layer's until an icon became a
+ * resource.
+ */
+export declare function toned(icon: IconLayer, want?: Tone): ImageVariant | undefined;
+/**
+ * What a published variant's file is called, keyed by what it holds.
+ *
+ * Beside `ICON_EXTENSION` rather than folded into it, for the reason that table gives: a ladder
+ * produces these four and never an SVG or an ICO, and answering `avif` for a mime it does not
+ * recognise would be a guess an icon cannot afford. Held to `for_variant` in
+ * services/apps/local/src/extension.rs by a test, the two being one fact in two languages.
+ */
+export declare const VARIANT_EXTENSION: Record<string, string>;
+/**
+ * Where one published file is fetched from: the content id and the extension that says how to
+ * read it, under `/object` like every other byte the CDN holds.
+ *
+ * Here rather than in each caller because the resolution that used to happen at build time now
+ * happens in three places -- a build writing the markdown target's address, a Worker rendering a
+ * page, a browser rendering the same page again -- and a URL spelled three ways is three chances
+ * to spell it wrong. The CDN is passed rather than picked: which one answers depends on the mode.
+ */
+export declare function objectUrl(cdnUrl: string, cid: string, extension: string): string;
+/**
+ * The variants a `srcset` can name, smallest first.
+ *
+ * Only the ones with pixels, because a `w` descriptor is a pixel count and a vector has none to
+ * state -- it is the `src`, and one file that serves every width needs no candidates beside it.
+ */
+export declare function rungs(image: ImageLayer): (ImageVariant & {
+  width: number;
+})[];
+/** Everything the markup needs about one picture, from the record and the CDN alone. */
+export type Picture = {
+  src: string;
+  srcset: string;
+  /** The intrinsic box, which is what reserves the space before anything is fetched. */
+  width: number;
+  height: number;
+  ratio: string;
+  /** The colour block painted under it while it arrives. Absent for a record holding no hash. */
+  placeholder?: string;
+};
+/**
+ * Which of a resource's files a picture is drawn from, and the refusal when it is not one.
+ *
+ * The second per-kind selector, beside `toned`, and one thing separates them: **a mark that does
+ * not resolve is absent and a picture that does not is an error.** A card's foot loses an
+ * ornament and still says where the link goes; an article loses what the paragraph is about, and
+ * a blank there is how a missing image becomes one nobody reports. So this throws, where the
+ * build refuses only what its committed manifest does not know -- spec/architecture/resource.md.
+ */
+export declare function pictured(rid: string, record: ParsedResource | undefined, cdnUrl: string): Picture;
+/**
+ * Every rid the blocks of one view name, each asked for once.
+ *
+ * A block declares its resources under a key that says so, and this reads that key and nothing
+ * else. What it replaces was a switch over block types, kept in the page that renders them,
+ * which grew an arm for every block that came to name one. The shape is what fixes that: with
+ * the roles on the block there is no list here to grow. Deduplicated, because two pictures of
+ * one subject are one question -- spec/architecture/resource.md, "One question per page".
+ */
+export declare function namedResources(blocks: readonly Block[]): string[];
+//#endregion

package/dist/artifacts/src/picture.js

@@ -0,0 +1,161 @@
+import { SCALABLE_MIMES, requireSegment } from "./resource.js";
+//#region artifacts/src/picture.ts
+/**
+* Choosing what to draw out of an image or icon layer: its size, the variant that covers a width,
+* the tone that suits a ground, and the picture a page renders for a rid. See
+* spec/architecture/resource.md.
+*/
+/** Step one: the intrinsic box, which every picture has. No branch and no decision. */
+function width(image) {
+	return image.dimension.width;
+}
+function height(image) {
+	return image.dimension.height;
+}
+function aspect(image) {
+	return image.dimension.aspect;
+}
+/** Step three: actual pixels, and `null` for a vector, which has none to report. */
+function resolution(image) {
+	return image.resolution ?? null;
+}
+/**
+* Whether this picture serves any size, which is the one place that knows which mimes scale.
+*
+* Asked of the variants because that is where a concrete mime is a fact; an absent `resolution`
+* says the same thing and covers a layer whose variants have not been derived yet.
+*/
+function scalable(image) {
+	return image.variants.some((file) => SCALABLE_MIMES.has(file.mime)) || !image.resolution;
+}
+/**
+* Step two, and the point of the other three: whether this can serve a target long edge.
+*
+* **The branch lives here.** A caller drawing a thumbnail never gets further than this line and
+* never learns that formats exist, which is what keeps `scalable` from being a condition repeated
+* in every caller. See spec/architecture/resource.md, "The image layer answers in four steps".
+*/
+function enough(image, want) {
+	if (scalable(image)) return true;
+	const pixels = resolution(image);
+	return pixels !== null && Math.max(pixels.width, pixels.height) >= want;
+}
+function longEdge(file) {
+	return file.resolution ? Math.max(file.resolution.width, file.resolution.height) : Infinity;
+}
+/**
+* Step four: the file to serve for a target long edge.
+*
+* The smallest rung that covers the target, because anything larger is weight a reader pays for and
+* nobody sees; the largest when none of them does, since upscaling is never done and the top rung
+* is the best answer that exists. See web's spec/architecture/media.md, "Variants stop where the
+* layout does".
+*/
+function best(image, want) {
+	const vector = image.variants.find((file) => SCALABLE_MIMES.has(file.mime));
+	if (vector) return vector;
+	const rungs = [...image.variants].sort((a, b) => longEdge(a) - longEdge(b));
+	return rungs.find((file) => longEdge(file) >= want) ?? rungs[rungs.length - 1];
+}
+/**
+* What an icon's file is spelled with, keyed by what is in it.
+*
+* Its own table rather than the variant one, for the reason `for_icon` is its own on the other
+* side: these bytes were encoded by somebody else's server and arrive as SVG or ICO, neither of
+* which a ladder ever produces -- and the ladder's table answers `avif` for anything it does not
+* recognise, which would be an address to a file nobody wrote. The twin of `icon_mime` in
+* services/apps/local/src/extension.rs, held to it by a test here.
+*/
+const ICON_EXTENSION = {
+	"image/svg+xml": "svg",
+	"image/png": "png",
+	"image/jpeg": "jpeg",
+	"image/x-icon": "ico"
+};
+/**
+* Which of an icon's files answers for a tone, and `undefined` when none does.
+*
+* A named tone is that tone or nothing: a caller handed the other one cannot tell it happened,
+* and would draw a light mark on a dark surface believing it had the right one. With none named
+* either will do, light first, an untinted mark being drawn for light backgrounds. The one place
+* that rule is written on this side, having been the alias layer's until an icon became a
+* resource.
+*/
+function toned(icon, want) {
+	return want ? icon.tones[want] : icon.tones.light ?? icon.tones.dark;
+}
+/**
+* What a published variant's file is called, keyed by what it holds.
+*
+* Beside `ICON_EXTENSION` rather than folded into it, for the reason that table gives: a ladder
+* produces these four and never an SVG or an ICO, and answering `avif` for a mime it does not
+* recognise would be a guess an icon cannot afford. Held to `for_variant` in
+* services/apps/local/src/extension.rs by a test, the two being one fact in two languages.
+*/
+const VARIANT_EXTENSION = {
+	"image/avif": "avif",
+	"image/webp": "webp",
+	"image/png": "png",
+	"image/jpeg": "jpeg"
+};
+/**
+* Where one published file is fetched from: the content id and the extension that says how to
+* read it, under `/object` like every other byte the CDN holds.
+*
+* Here rather than in each caller because the resolution that used to happen at build time now
+* happens in three places -- a build writing the markdown target's address, a Worker rendering a
+* page, a browser rendering the same page again -- and a URL spelled three ways is three chances
+* to spell it wrong. The CDN is passed rather than picked: which one answers depends on the mode.
+*/
+function objectUrl(cdnUrl, cid, extension) {
+	return `${cdnUrl}/object/${cid}.${extension}`;
+}
+/**
+* The variants a `srcset` can name, smallest first.
+*
+* Only the ones with pixels, because a `w` descriptor is a pixel count and a vector has none to
+* state -- it is the `src`, and one file that serves every width needs no candidates beside it.
+*/
+function rungs(image) {
+	return image.variants.flatMap((file) => file.resolution ? [{
+		...file,
+		width: file.resolution.width
+	}] : []).toSorted((a, b) => a.width - b.width);
+}
+/**
+* Which of a resource's files a picture is drawn from, and the refusal when it is not one.
+*
+* The second per-kind selector, beside `toned`, and one thing separates them: **a mark that does
+* not resolve is absent and a picture that does not is an error.** A card's foot loses an
+* ornament and still says where the link goes; an article loses what the paragraph is about, and
+* a blank there is how a missing image becomes one nobody reports. So this throws, where the
+* build refuses only what its committed manifest does not know -- spec/architecture/resource.md.
+*/
+function pictured(rid, record, cdnUrl) {
+	if (!record) throw new Error(`no record for resource ${rid}, which an article draws`);
+	const image = requireSegment(record, "image");
+	const file = best(image, width(image));
+	if (!file) throw new Error(`resource ${rid} publishes no file to draw`);
+	return {
+		src: objectUrl(cdnUrl, file.content, VARIANT_EXTENSION[file.mime] ?? "avif"),
+		srcset: rungs(image).map((rung) => `${objectUrl(cdnUrl, rung.content, VARIANT_EXTENSION[rung.mime] ?? "avif")} ${rung.width}w`).join(", "),
+		width: width(image),
+		height: height(image),
+		ratio: aspect(image),
+		placeholder: image.placeholder
+	};
+}
+/**
+* Every rid the blocks of one view name, each asked for once.
+*
+* A block declares its resources under a key that says so, and this reads that key and nothing
+* else. What it replaces was a switch over block types, kept in the page that renders them,
+* which grew an arm for every block that came to name one. The shape is what fixes that: with
+* the roles on the block there is no list here to grow. Deduplicated, because two pictures of
+* one subject are one question -- spec/architecture/resource.md, "One question per page".
+*/
+function namedResources(blocks) {
+	return [...new Set(blocks.flatMap((block) => "resources" in block ? Object.values(block.resources ?? {}) : []))];
+}
+//#endregion
+export { ICON_EXTENSION, VARIANT_EXTENSION, aspect, best, enough, height, namedResources, objectUrl, pictured, resolution, rungs, scalable, toned, width };