@morphemecms/cms 0.0.0-stage → 0.1.0

package/lib/dynamic-colors.ts

@@ -0,0 +1,426 @@
+// Dynamic colour (Material 3, https://m3.material.io/styles/color/system/how-the-system-works): all the
+// site's colours, in light and dark mode, made from one source colour. The source colour gives tonal
+// palettes in HCT (Material's colour space), a scheme variant picks how much colour each palette has, and
+// the contrast level how far apart the tones of text and its background are. The generator ("Farver" › "Generator")
+// uses a colour harmony instead of a variant: the source colour's hue and chroma give the primary palette, and the
+// harmony puts the secondary and tertiary palettes round the colour wheel from it (HARMONIES), as on a colour wheel. Each of the site's colours
+// takes the tone of a Material colour role ("Farver": colorRoles in @site/colors), so text stays
+// readable in both modes. The site's file of colours keeps the choice ("dynamic") beside the colours it
+// gave, so the site itself never needs this: only the editor makes them (Colors.tsx).
+// Content-based colour (https://m3.material.io/styles/color/dynamic/content-based-source) is the other
+// source Material has: every page takes its colours from its own picture, made the same way when
+// the site is built (packages/editor/site/pageColors.ts), while an app says so (the app "Indholdsbaserede farver", with the choice
+// in its settings), or a theme asks for it.
+// No React or browser here: the check before the build uses it too.
+import {
+  Blend,
+  DislikeAnalyzer,
+  DynamicScheme,
+  Hct,
+  QuantizerCelebi,
+  SchemeContent,
+  SchemeExpressive,
+  SchemeFidelity,
+  SchemeFruitSalad,
+  SchemeMonochrome,
+  SchemeNeutral,
+  SchemeRainbow,
+  SchemeTonalSpot,
+  SchemeVibrant,
+  Score,
+  TemperatureCache,
+  TonalPalette,
+  argbFromHex,
+  argbFromRgb,
+  hexFromArgb,
+  sanitizeDegreesDouble,
+} from '@material/material-color-utilities';
+import { isColor, MODES, type ColorSet, type Colors, type Mode } from './colors';
+
+/** Material's scheme variants, in the order they are offered (the first is Material's default). */
+export const VARIANTS = [
+  'tonalSpot',
+  'neutral',
+  'vibrant',
+  'expressive',
+  'fidelity',
+  'content',
+  'monochrome',
+  'rainbow',
+  'fruitSalad',
+] as const;
+export type Variant = (typeof VARIANTS)[number];
+
+const SCHEMES: Record<Variant, new (source: Hct, isDark: boolean, contrast: number) => DynamicScheme> = {
+  tonalSpot: SchemeTonalSpot,
+  neutral: SchemeNeutral,
+  vibrant: SchemeVibrant,
+  expressive: SchemeExpressive,
+  fidelity: SchemeFidelity,
+  content: SchemeContent,
+  monochrome: SchemeMonochrome,
+  rainbow: SchemeRainbow,
+  fruitSalad: SchemeFruitSalad,
+};
+
+/** Material's contrast levels, by name, and the level each is. */
+export const CONTRASTS = { standard: 0, medium: 0.5, high: 1 } as const;
+export type Contrast = keyof typeof CONTRASTS;
+
+/** The colour harmonies the generator offers, in the order they are offered (the first is where it starts). */
+export const HARMONIES = ['analogous', 'monochromatic', 'complementary', 'splitComplementary', 'triadic'] as const;
+export type Harmony = (typeof HARMONIES)[number];
+
+// Each harmony's secondary and tertiary palette: its hue, from the source colour (with Material's warm and cool
+// colours, TemperatureCache, where Material has the harmony: its analogous colours and its complement, which go better
+// with the source colour than a fixed turn round the wheel; else a turn), and its share of the harmony's chroma
+// (harmonyChroma). A palette on the source colour's own hue has less of it, so the two still differ.
+type Place = (source: Hct, warmCool: () => TemperatureCache) => number;
+const HARMONY: Record<Harmony, Record<'secondary' | 'tertiary', [hue: Place, share: number]>> = {
+  analogous: { secondary: [(_, w) => w().analogous(5, 12)[1].hue, 1], tertiary: [(_, w) => w().analogous(5, 12)[3].hue, 1] },
+  monochromatic: { secondary: [(s) => s.hue, 0.45], tertiary: [(s) => s.hue, 0.75] },
+  complementary: { secondary: [(s) => s.hue, 0.45], tertiary: [(_, w) => w().complement.hue, 1] },
+  splitComplementary: { secondary: [(_, w) => w().complement.hue - 30, 1], tertiary: [(_, w) => w().complement.hue + 30, 1] },
+  triadic: { secondary: [(s) => s.hue + 120, 1], tertiary: [(s) => s.hue - 120, 1] },
+};
+
+// The secondary and tertiary colours' chroma: the source colour's, but at least 32 and at most 48, so they are neither
+// grey nor neon (a nearly grey source colour gives grey ones: at most twice its own).
+const harmonyChroma = (chroma: number) => Math.min(48, Math.max(chroma, Math.min(32, chroma * 2)));
+// The source colour's chroma that gives a harmony chroma (the other way round).
+function sourceChromaFor(wanted: number, chroma: number): number {
+  if (wanted < 32) return wanted / 2;
+  if (wanted >= 48) return Math.max(chroma, 48);
+  if (wanted === 32) return chroma >= 16 && chroma <= 32 ? chroma : 32;
+  return wanted;
+}
+
+// The hue and chroma of a harmony's secondary or tertiary palette for a source colour (the warm and cool colours worked
+// out once for the last source colour, as dragging asks for them many times).
+let warmCool: { argb: number; cache: TemperatureCache } | undefined;
+function placed(source: Hct, harmony: Harmony, which: 'secondary' | 'tertiary'): { hue: number; chroma: number } {
+  const w = () => {
+    if (warmCool?.argb !== source.toInt()) warmCool = { argb: source.toInt(), cache: new TemperatureCache(source) };
+    return warmCool.cache;
+  };
+  const [hue, share] = HARMONY[harmony][which];
+  return { hue: sanitizeDegreesDouble(hue(source, w)), chroma: harmonyChroma(source.chroma) * share };
+}
+
+/** The generator's three base colours, in order: the source colour (primary), the second (secondary) and the third
+ * (tertiary). */
+export const BASE_COLORS = ['source', 'secondary', 'tertiary'] as const;
+export type BaseColor = (typeof BASE_COLORS)[number];
+
+/** The choice the colours are made from, as the file of colours keeps it: the source colour, a harmony (the
+ * generator's) or a variant (Material's, as a file written before the harmonies has it), never both, and the contrast.
+ * The source colour can be locked (`sourceLocked`): the wheel does not move it, and the second and third colours,
+ * which the harmony makes from it, cannot be changed on their own. */
+export type Dynamic = {
+  source: string;
+  harmony?: Harmony;
+  variant?: Variant;
+  contrast: Contrast;
+  sourceLocked?: boolean;
+};
+
+/** The choice for content-based colour, as an app gives it (AppDefinition.pageColors): the source colour is the picture's. */
+export type ContentBased = { variant: Variant; contrast: Contrast };
+
+/** The variant Material uses for content-based colour: the one closest to the picture. */
+export const CONTENT_VARIANT: Variant = 'content';
+
+/** Material's colour roles a site's colour can take, and one Material has not: `primaryHover`, the primary
+ * colour a little further from the text on it (a button under the mouse). */
+export type Role =
+  | 'surface'
+  | 'surfaceDim'
+  | 'surfaceBright'
+  | 'surfaceContainerLowest'
+  | 'surfaceContainerLow'
+  | 'surfaceContainer'
+  | 'surfaceContainerHigh'
+  | 'surfaceContainerHighest'
+  | 'onSurface'
+  | 'onSurfaceVariant'
+  | 'outline'
+  | 'outlineVariant'
+  | 'primary'
+  | 'onPrimary'
+  | 'primaryContainer'
+  | 'onPrimaryContainer'
+  | 'secondary'
+  | 'onSecondary'
+  | 'secondaryContainer'
+  | 'onSecondaryContainer'
+  | 'tertiary'
+  | 'onTertiary'
+  | 'tertiaryContainer'
+  | 'onTertiaryContainer'
+  | 'error'
+  | 'onError'
+  | 'errorContainer'
+  | 'onErrorContainer'
+  | 'inverseSurface'
+  | 'inverseOnSurface'
+  | 'inversePrimary'
+  | 'primaryHover';
+
+/** The role each of a site's colours takes, by its name; one role, or one in each mode. */
+export type ColorRoles = Record<string, Role | Record<Mode, Role>>;
+
+// How many tones a button under the mouse moves away from its text.
+const HOVER = 5;
+
+function roleColor(scheme: DynamicScheme, role: Role): string {
+  if (role !== 'primaryHover') return hexFromArgb(scheme[role]);
+  const primary = Hct.fromInt(scheme.primary);
+  const away = Hct.fromInt(scheme.onPrimary).tone > primary.tone ? -HOVER : HOVER;
+  return hexFromArgb(Hct.from(primary.hue, primary.chroma, Math.min(100, Math.max(0, primary.tone + away))).toInt());
+}
+
+// Material's error colour, which a harmony turns a little towards the source colour (Blend.harmonize, as Material
+// harmonizes its static colours), so it sits better with the others.
+const ERROR = Hct.from(25, 84, 40).toInt();
+// The variant whose rules a harmony's scheme follows for each role's tone (Material's own for tonal spot).
+const TONAL_SPOT = new SchemeTonalSpot(Hct.fromInt(ERROR), false, 0).variant;
+
+/** Material's scheme for a choice, in a mode: its harmony's or its variant's. */
+function schemeOf(dynamic: Dynamic, isDark: boolean): DynamicScheme {
+  const source = Hct.fromInt(argbFromHex(dynamic.source));
+  const contrastLevel = CONTRASTS[dynamic.contrast];
+  if (!dynamic.harmony) return new SCHEMES[dynamic.variant ?? VARIANTS[0]](source, isDark, contrastLevel);
+  const { hue, chroma } = source;
+  const around = (which: 'secondary' | 'tertiary') => {
+    const p = placed(source, dynamic.harmony!, which);
+    return TonalPalette.fromHueAndChroma(p.hue, p.chroma);
+  };
+  const scheme = new DynamicScheme({
+    sourceColorArgb: source.toInt(),
+    variant: TONAL_SPOT,
+    contrastLevel,
+    isDark,
+    primaryPalette: TonalPalette.fromHueAndChroma(hue, chroma),
+    secondaryPalette: around('secondary'),
+    tertiaryPalette: around('tertiary'),
+    // The surfaces and text a little of the source colour, as much as tonal spot's at most.
+    neutralPalette: TonalPalette.fromHueAndChroma(hue, Math.min(chroma / 6, 6)),
+    neutralVariantPalette: TonalPalette.fromHueAndChroma(hue, Math.min(chroma / 4.5, 8)),
+  });
+  scheme.errorPalette = TonalPalette.fromHueAndChroma(Hct.fromInt(Blend.harmonize(ERROR, source.toInt())).hue, 84);
+  return scheme;
+}
+
+/** The site's colours in both modes, made from the choice, each by its role. */
+export function dynamicColors(dynamic: Dynamic, roles: ColorRoles): Colors {
+  const set = (mode: Mode): ColorSet => {
+    const scheme = schemeOf(dynamic, mode === 'dark');
+    return Object.fromEntries(
+      Object.entries(roles).map(([name, role]) => [name, roleColor(scheme, typeof role === 'string' ? role : role[mode])]),
+    );
+  };
+  return { light: set('light'), dark: set('dark') };
+}
+
+// The colours a file of colours written before they were among the site's had in the theme, from the others (mixed in
+// sRGB, as the theme's CSS mixed them): the surface containers a step each towards the text from the surfaces tinted
+// with the light colour, the lowest the surfaces, the outline between the quiet text and the surfaces, the inverse
+// colours the text's on the page's with the light colour for its buttons, and the error colours the accent colours.
+const MIXED: Record<string, (set: ColorSet) => string | undefined> = {
+  'surface-container-lowest': (c) => c.surface,
+  'surface-container-low': (c) => mix(c.ink, 0.03, mix(c.tint, 0.3, c.surface)),
+  'surface-container': (c) => mix(c.ink, 0.05, mix(c.tint, 0.3, c.surface)),
+  'surface-container-high': (c) => mix(c.ink, 0.08, mix(c.tint, 0.3, c.surface)),
+  'surface-container-highest': (c) => mix(c.ink, 0.11, mix(c.tint, 0.3, c.surface)),
+  outline: (c) => mix(c.muted, 0.7, c.surface),
+  'inverse-surface': (c) => c.ink,
+  'inverse-on-surface': (c) => c.bg,
+  'inverse-primary': (c) => c.tint,
+  error: (c) => c.accent,
+  'on-error': (c) => c['on-accent'],
+  'error-container': (c) => c['accent-container'],
+  'on-error-container': (c) => c['on-accent-container'],
+};
+
+/** `share` of colour `a` in colour `b`, in sRGB; undefined when one is not a colour. */
+function mix(a: string | undefined, share: number, b: string | undefined): string | undefined {
+  if (!isColor(a) || !isColor(b)) return undefined;
+  const channel = (hex: string, i: number) => parseInt(hex.slice(i, i + 2), 16);
+  return `#${[1, 3, 5]
+    .map((i) =>
+      Math.round(channel(a, i) * share + channel(b, i) * (1 - share))
+        .toString(16)
+        .padStart(2, '0'),
+    )
+    .join('')}`;
+}
+
+/** The colours of a file of colours with those of `roles` it does not have (one written before they were among the
+ * site's): made from its choice of dynamic colour, when it has one, else as the theme mixed them from the others. What
+ * cannot be made stays missing, for colorProblems to say. */
+export function completeColors(colors: Colors, roles: ColorRoles): Colors {
+  const missing = (set: ColorSet | undefined) => !!set && Object.keys(roles).some((name) => !isColor(set[name]));
+  if (!MODES.some((mode) => missing(colors[mode]))) return colors;
+  const made = colors.dynamic !== undefined && !dynamicProblems(colors.dynamic).length ? dynamicColors(colors.dynamic, roles) : undefined;
+  const complete = (mode: Mode): ColorSet => {
+    const set = colors[mode];
+    if (!missing(set)) return set;
+    const from = (name: string) => (made ? made[mode][name] : MIXED[name]?.(set));
+    const added = Object.keys(roles)
+      .filter((name) => !isColor(set[name]))
+      .map((name) => [name, from(name)])
+      .filter(([, value]) => isColor(value));
+    return { ...set, ...Object.fromEntries(added) };
+  };
+  return { ...colors, light: complete('light'), dark: complete('dark') };
+}
+
+/** What is wrong with a choice of dynamic colour, a line for each ('dynamic.variant: "rød"'), or []: the one in a file
+ * of colours (`dynamic`), or one for content-based colour (`contentBased`, which has no source colour). */
+export function dynamicProblems(value: unknown, key: 'dynamic' | 'contentBased' = 'dynamic'): string[] {
+  const d = (value ?? {}) as Record<string, unknown>;
+  const bad = (name: string) => `${key}.${name}: ${JSON.stringify(d[name] ?? null)}`;
+  // A harmony instead of a variant only in a file of colours, the generator's.
+  const harmony = key === 'dynamic' && d.harmony !== undefined;
+  return [
+    ...(key === 'contentBased' || isColor(d.source) ? [] : [bad('source')]),
+    ...(harmony ? (HARMONIES.includes(d.harmony as Harmony) ? [] : [bad('harmony')]) : []),
+    ...((harmony ? d.variant === undefined : VARIANTS.includes(d.variant as Variant)) ? [] : [bad('variant')]),
+    ...(Object.hasOwn(CONTRASTS, d.contrast as string) ? [] : [bad('contrast')]),
+    // The lock on the source colour, only in a file of colours.
+    ...(d.sourceLocked === undefined || (key === 'dynamic' && d.sourceLocked === true) ? [] : [bad('sourceLocked')]),
+  ];
+}
+
+// Material's quantizer in JavaScript (QuantizerWsmeans) starts its clusters from Math.random, so the same picture could
+// give other colours each time it is read (and each build other colours for a page); seeded as Material's Java and Dart
+// versions are (0x42688), it gives the same. The quantizer runs at once, so nothing else gets the seeded numbers.
+function seeded<T>(run: () => T): T {
+  const random = Math.random;
+  let seed = 0x42688;
+  // mulberry32
+  Math.random = () => {
+    seed = (seed + 0x6d2b79f5) | 0;
+    let n = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    n = (n + Math.imul(n ^ (n >>> 7), 61 | n)) ^ n;
+    return ((n ^ (n >>> 14)) >>> 0) / 4294967296;
+  };
+  try {
+    return run();
+  } finally {
+    Math.random = random;
+  }
+}
+
+/** The colours in a picture that are best as a source colour, best first (at most four): a picture's pixels
+ * as RGBA bytes (a canvas's ImageData, or sharp's raw output with an alpha channel). Material's own way:
+ * quantized, then scored. Only the picture's own: none for one without colour enough (a grey one), where
+ * Material's score would give its fallback colour (Google blue). */
+export function sourceColorsOf(bytes: Uint8ClampedArray): string[] {
+  const pixels: number[] = [];
+  for (let i = 0; i < bytes.length; i += 4) if (bytes[i + 3] === 255) pixels.push(argbFromRgb(bytes[i], bytes[i + 1], bytes[i + 2]));
+  const population = seeded(() => QuantizerCelebi.quantize(pixels, 128));
+  return Score.score(population, { desired: 4 })
+    .filter((color) => population.has(color))
+    .map(hexFromArgb);
+}
+
+// The colour wheel ("Farver" › "Generator", ColorWheel in the editor): each hue at its angle, clockwise from the top,
+// and its chroma as the distance from the middle, as a share of the most chroma the hue can have in sRGB, so the
+// edge is every hue at its most colourful and the middle grey.
+
+// The most chroma each whole degree of hue can have, and the tone it has it at, worked out once each.
+const most = new Map<number, { chroma: number; tone: number }>();
+function mostChroma(hue: number): { chroma: number; tone: number } {
+  const key = Math.round(sanitizeDegreesDouble(hue)) % 360;
+  let found = most.get(key);
+  if (!found) {
+    found = { chroma: 0, tone: 50 };
+    for (let tone = 5; tone <= 95; tone += 2.5) {
+      const chroma = Hct.from(key, 200, tone).chroma;
+      if (chroma > found.chroma) found = { chroma, tone };
+    }
+    most.set(key, found);
+  }
+  return found;
+}
+
+/** A dot on the colour wheel: where it is (x and y from -1 to 1, from the middle; y down) and its colour. */
+export type WheelDot = { x: number; y: number; color: string };
+
+// A colour with a hue and chroma (at most what the hue can have) in `tone`, or, where the tone cannot have that much
+// chroma, where the hue is most colourful, so its own hue and chroma are the ones asked for.
+function colorAt(hue: number, chroma: number, tone?: number): string {
+  const most = mostChroma(hue);
+  const wanted = Math.min(chroma, most.chroma);
+  const inTone = tone === undefined ? undefined : Hct.from(hue, wanted, tone);
+  return hexFromArgb((inTone && inTone.chroma >= wanted - 1 ? inTone : Hct.from(hue, wanted, most.tone)).toInt());
+}
+
+// A colour on the wheel: where its hue and chroma are, and its colour (colorAt).
+function onWheel(hue: number, chroma: number, tone?: number): WheelDot {
+  const r = Math.min(1, chroma / mostChroma(hue).chroma);
+  const angle = (hue * Math.PI) / 180;
+  return { x: r * Math.sin(angle), y: -r * Math.cos(angle), color: colorAt(hue, chroma, tone) };
+}
+
+/** A choice's three base colours, as dots on the colour wheel: its primary (the source colour's hue and chroma),
+ * secondary and tertiary palette, in that order (BASE_COLORS). The first is the source colour itself (in its tone); the
+ * others are shown where their hue is clearest (most colourful: a light yellow, a deep blue), never in a tone Material
+ * dislikes (DislikeAnalyzer: a dark olive), so they look as they go together, not as one tone of each. */
+export function wheelDots(dynamic: Dynamic): WheelDot[] {
+  const scheme = schemeOf(dynamic, false);
+  const { tone } = Hct.fromInt(argbFromHex(dynamic.source));
+  return [scheme.primaryPalette, scheme.secondaryPalette, scheme.tertiaryPalette].map((p, i) => {
+    const dot = onWheel(p.hue, p.chroma, i ? undefined : tone);
+    return i ? { ...dot, color: hexFromArgb(DislikeAnalyzer.fixIfDisliked(Hct.fromInt(argbFromHex(dot.color))).toInt()) } : dot;
+  });
+}
+
+/** Whether a base colour can be changed on its own (its edit sheet): the source colour always; the secondary and
+ * tertiary colour while the source colour is not locked, as they are made from it. */
+export const canSetBaseColor = (dynamic: Dynamic, which: BaseColor) => which === 'source' || !dynamic.sourceLocked;
+
+/** A choice with one of its base colours set to `color` (its edit sheet): the source colour is that colour (locked with
+ * `lock`); for the secondary or tertiary colour (canSetBaseColor) the source colour turns, in its tone, so the harmony
+ * (the first, without one) gives that colour's hue, or the closest it can (Material's warm and cool colours do not
+ * reach every hue: no colour has a purple complement), and takes the chroma that gives that colour's chroma. */
+export function withBaseColor(dynamic: Dynamic, which: BaseColor, color: string, lock = false): Dynamic {
+  if (which === 'source') return { ...dynamic, source: color, ...(lock && { sourceLocked: true }) };
+  if (!canSetBaseColor(dynamic, which)) return dynamic;
+  const harmony = dynamic.harmony ?? HARMONIES[0];
+  const target = Hct.fromInt(argbFromHex(color));
+  const source = Hct.fromInt(argbFromHex(dynamic.source));
+  const chroma = sourceChromaFor(target.chroma / HARMONY[harmony][which][1], source.chroma);
+  // How far the harmony's colour is from the target's hue (degrees, signed), from a source hue.
+  const off = (hue: number) =>
+    sanitizeDegreesDouble(target.hue - placed(Hct.from(hue, chroma, source.tone), harmony, which).hue + 180) - 180;
+  // The closest of every 10 degrees round the wheel, then closer in a few steps from there.
+  let best = { hue: source.hue, off: off(source.hue) };
+  for (let hue = 0; hue < 360; hue += 10) {
+    const o = off(hue);
+    if (Math.abs(o) < Math.abs(best.off)) best = { hue, off: o };
+  }
+  for (let step = 0; step < 6 && Math.abs(best.off) >= 0.5; step++) {
+    const hue = sanitizeDegreesDouble(best.hue + best.off);
+    const o = off(hue);
+    if (Math.abs(o) >= Math.abs(best.off)) break;
+    best = { hue, off: o };
+  }
+  const { variant: _, ...rest } = dynamic;
+  return { ...rest, harmony, source: hexFromArgb(Hct.from(best.hue, chroma, source.tone).toInt()) };
+}
+
+/** The source colour at a point on the colour wheel (x and y from -1 to 1; further out is the edge): its hue and
+ * chroma, at the tone its hue is most colourful at. */
+export function wheelColor(x: number, y: number): string {
+  const hue = sanitizeDegreesDouble((Math.atan2(x, -y) * 180) / Math.PI);
+  const { chroma, tone } = mostChroma(hue);
+  return hexFromArgb(Hct.from(hue, chroma * Math.min(1, Math.hypot(x, y)), tone).toInt());
+}
+
+/** The colours round the colour wheel's edge, from the top clockwise (`steps` of them), and the grey in its middle. */
+export function wheelColors(steps = 36): { edge: string[]; middle: string } {
+  const edge = Array.from({ length: steps }, (_, i) => onWheel((i * 360) / steps, 200).color);
+  return { edge, middle: hexFromArgb(Hct.from(0, 0, 70).toInt()) };
+}

package/lib/git.d.mts

@@ -0,0 +1,24 @@
+/** Git's id for a file's content: sha1 of "blob <size>\0<content>". @param {Uint8Array} bytes */
+export function blobId(bytes: Uint8Array): Promise<string>;
+/**
+ * A folder's entries in git's order: by the names' bytes, a folder's as if it ended with "/".
+ * @template {{ name: string, mode: number }} E
+ * @param {E[]} entries
+ * @returns {E[]}
+ */
+export function sortTree<E extends {
+    name: string;
+    mode: number;
+}>(entries: E[]): E[];
+/**
+ * Git's id for a folder: sha1 of "tree <size>\0" and its entries in git's order, each "<mode in octal> <name>\0" and
+ * the 20 bytes of its id.
+ * @param {{ name: string, oid: string, mode: number }[]} entries
+ */
+export function treeId(entries: {
+    name: string;
+    oid: string;
+    mode: number;
+}[]): Promise<string>;
+/** The mode git gives a folder in a tree (040000), as GitHub's GraphQL API gives modes: a number. */
+export const TREE_MODE: 16384;

package/lib/git.mjs

@@ -0,0 +1,64 @@
+// Git's ids for a file's content (a blob) and a folder (a tree), as git computes them, for the editor
+// (packages/editor/src/github.ts) and the site's Worker (packages/editor/worker/files.js): what either gets from GitHub, R2 or the site
+// is checked against them, so a file is never kept or saved broken. No Node, no DOM: both run it.
+
+const encoder = new TextEncoder();
+
+/** Git's id for a file's content: sha1 of "blob <size>\0<content>". @param {Uint8Array} bytes */
+export async function blobId(bytes) {
+  return sha1(join([encoder.encode(`blob ${bytes.length}\0`), bytes]));
+}
+
+/** The mode git gives a folder in a tree (040000), as GitHub's GraphQL API gives modes: a number. */
+export const TREE_MODE = 0o40000;
+
+/**
+ * A folder's entries in git's order: by the names' bytes, a folder's as if it ended with "/".
+ * @template {{ name: string, mode: number }} E
+ * @param {E[]} entries
+ * @returns {E[]}
+ */
+export function sortTree(entries) {
+  const keyed = entries.map((e) => ({ e, key: encoder.encode(e.mode === TREE_MODE ? `${e.name}/` : e.name) }));
+  return keyed.sort((a, b) => compare(a.key, b.key)).map(({ e }) => e);
+}
+
+/**
+ * Git's id for a folder: sha1 of "tree <size>\0" and its entries in git's order, each "<mode in octal> <name>\0" and
+ * the 20 bytes of its id.
+ * @param {{ name: string, oid: string, mode: number }[]} entries
+ */
+export async function treeId(entries) {
+  const body = join(sortTree(entries).flatMap((e) => [encoder.encode(`${e.mode.toString(8)} ${e.name}\0`), hexBytes(e.oid)]));
+  return sha1(join([encoder.encode(`tree ${body.length}\0`), body]));
+}
+
+/** @param {Uint8Array} a @param {Uint8Array} b */
+function compare(a, b) {
+  for (let i = 0; i < Math.min(a.length, b.length); i++) if (a[i] !== b[i]) return a[i] - b[i];
+  return a.length - b.length;
+}
+
+/** @param {Uint8Array[]} parts */
+function join(parts) {
+  const all = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    all.set(p, at);
+    at += p.length;
+  }
+  return all;
+}
+
+/** @param {string} hex */
+function hexBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(hex.slice(2 * i, 2 * i + 2), 16);
+  return bytes;
+}
+
+/** @param {Uint8Array} bytes */
+async function sha1(bytes) {
+  const hash = new Uint8Array(await crypto.subtle.digest('SHA-1', bytes));
+  return Array.from(hash, (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/lib/hooks.ts

@@ -0,0 +1,51 @@
+// The places where an app may change how the site does something of its own, rather than add to it (a block, a kind,
+// a list, its code on every page): each a file in the app's folder, hooks/<place>.ts, whose default export the site's
+// build runs, while the app is installed, for every page. The site gives it what it needs to know and the tools it may
+// use, and keeps what it gives back only when it is right; an app reaches nothing of the site but that. Before an app
+// is installed, its page says what it changes ("Rettigheder", needsOf in src/store.ts, from the files in hooks/).
+//   page-colors  the colours of a page (PageColorsHook): given the page's colours so far (the site's, "Farver", or those
+//                of an app before it), its pictures and the app's settings, it gives the page other colours, or none.
+//                The site runs it in packages/editor/site/pageColors.ts, which a theme calls for every page (Base.astro).
+// No React, browser or Node here: the editor, the build and the check before it use it.
+import type { Colors } from './colors';
+import type { ColorRoles } from './dynamic-colors';
+
+/** The places an app may change the site, by the name of their file in its hooks/ (without .ts). */
+export const APP_HOOKS = ['page-colors'] as const;
+export type AppHook = (typeof APP_HOOKS)[number];
+
+/** The places an app changes, from the paths of the files in its folder (hooks/page-colors.ts: 'page-colors'), and
+ * the files there that are no such place. */
+export function hooksOf(files: string[]): { hooks: AppHook[]; unknown: string[] } {
+  const there = files.filter((f) => f.startsWith('hooks/'));
+  const name = (f: string) => f.slice('hooks/'.length).replace(/\.ts$/, '');
+  return {
+    hooks: APP_HOOKS.filter((h) => there.includes(`hooks/${h}.ts`)),
+    unknown: there.filter((f) => !f.endsWith('.ts') || !(APP_HOOKS as readonly string[]).includes(name(f))),
+  };
+}
+
+/** What the site gives an app's hook for a page's colours. */
+export type PageColorsPage = {
+  /** The page's address on the site ("/om-mig/"). */
+  path: string;
+  /** The page's colours so far: the site's own, or those an app before it gave. */
+  colors: Colors;
+  /** The page's pictures, in the order they are on it (its own first, then those in its text and blocks), and last
+   * the one it is shared with; their addresses on the site. */
+  pictures: string[];
+  /** The app's settings, as saved in the editor over those it starts with. */
+  settings: Record<string, any>;
+  /** The role each of the site's colours takes in a Material 3 scheme (colorRoles), for dynamicColors. */
+  roles: ColorRoles;
+  /** A picture's pixels as RGBA bytes, made small (at most 128 px), as sourceColorsOf takes them; undefined for one
+   * that cannot be read. */
+  pixels: (picture: string) => Promise<Uint8ClampedArray | undefined>;
+  /** Whether the text in colours can be read on its background in both modes, as the site requires (WCAG AA). */
+  readable: (colors: Colors) => boolean;
+};
+
+/** An app's hook for a page's colours (hooks/page-colors.ts): other colours for the page, in both modes, each of the
+ * site's by its name; or undefined to leave them. Colours that are not the site's, or hard to read, are not used. */
+export type PageColorsHook = (page: PageColorsPage) => Colors | undefined | Promise<Colors | undefined>;
+export const definePageColors = (hook: PageColorsHook) => hook;

package/lib/inline.ts

@@ -0,0 +1,20 @@
+// A short text the site's owner writes as text in the editor (a page's introduction, the text under a section's
+// heading), for a component that shows it inside its own <p>: bold, italic and links as they were
+// written (Markdown, Astro's pipeline: typographic quotes too). Paragraphs are separated by a line break;
+// anything that cannot stand inside a <p> (a list, a picture) is shown as its text.
+import { createMarkdownProcessor } from '@astrojs/markdown-remark';
+import { inlineOf } from './markdown';
+
+let processor: ReturnType<typeof createMarkdownProcessor> | undefined;
+
+export async function inlineHtml(markdown: string): Promise<string> {
+  processor ??= createMarkdownProcessor();
+  return inlineOf((await (await processor).render(markdown)).code.trim());
+}
+
+/** A longer text the site's owner writes in the editor (an answer in "Spørgsmål og svar") as HTML: paragraphs,
+ * lists, bold, italic and links. */
+export async function markdownHtml(markdown: string): Promise<string> {
+  processor ??= createMarkdownProcessor();
+  return (await (await processor).render(markdown)).code.trim();
+}