@immediately-run/grove 0.1.1 → 0.1.3

package/src/lib/themeAssets.ts

@@ -0,0 +1,143 @@
+// Engine-resolved theme assets (R3-315; plan 05-content-carried-themes §4).
+//
+// A theme DECLARES its fonts and named assets (`fonts: [{family, src, weight,
+// style}]`, `assets: {<name>: <relPath>}`, resolved relative to the declaring
+// file); the ENGINE reads the bytes off the fs, mints a `blob:` URL for each, and
+// hands the result to CSS — an `@font-face` rule per font (emitted into the
+// engine-owned cascade layer) and a `--asset-<name>` custom property per asset.
+// Content never names a network location at all, which is the point: `blob:` is
+// permitted by `img-src`, `font-src` AND `style-src` in every stance including
+// M3, so one mechanism serves fork, dispatch and library modes — and the wiki
+// renders its faces with the network off, in every stance.
+//
+// The revoke scope is the THEME'S lifetime, not a component's — `useObjectUrl`'s
+// component-scoped revoke does not fit an asset set that outlives any single
+// surface, so this module owns the lifecycle explicitly: `revoke()` releases
+// every minted URL, and the switching surface calls it on teardown.
+//
+// DEGRADE, NEVER BREAK: a missing font file skips that `@font-face` (the token's
+// fallback stack answers); a missing named asset skips its var (the var()'s own
+// fallback answers). Nothing throws and nothing renders a broken glyph.
+//
+// The minted URLs carry no path information (`blob:` + origin), so under dispatch
+// the chroot prefix cannot reach a URL or a `@font-face` src by construction —
+// asserted, not assumed, in the tests.
+
+import { resolvePath } from './assetPath';
+
+/** One declared webfont. `src` is relative to the declaring file (or `/…` absolute). */
+export interface FontDeclaration {
+  family: string;
+  src: string;
+  /** CSS `font-weight` descriptor, e.g. `'400 700'` or `'700'`. */
+  weight?: string;
+  /** CSS `font-style` descriptor, e.g. `'normal'` | `'italic'`. */
+  style?: string;
+}
+
+/** The asset declarations a theme (or the engine's own default set) carries. */
+export interface ThemeAssetDeclarations {
+  fonts?: FontDeclaration[];
+  assets?: Record<string, string>;
+}
+
+/** The minted result: CSS the engine owns, plus the revoke handle. */
+export interface MintedThemeAssets {
+  /** `@font-face` rules with `blob:` srcs — the caller emits these inside the
+   *  engine cascade layer. Empty when nothing declared or everything degraded. */
+  fontFaceCss: string;
+  /** A `.grove-root` rule assigning `--asset-<name>: url(blob:…)` per minted
+   *  asset — empty when nothing declared or everything degraded. */
+  assetVarsCss: string;
+  /** How many URLs were minted (observable for leak tests). */
+  minted: number;
+  /** Release every minted URL. Idempotent. */
+  revoke(): void;
+}
+
+/** The bytes-read the minter needs — injected so tests spy and fault-inject. */
+export type AssetReader = (absPath: string) => Promise<Uint8Array<ArrayBuffer> | string>;
+
+const FONT_MIME: Record<string, string> = {
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+};
+const IMAGE_MIME: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  avif: 'image/avif',
+};
+
+function ext(p: string): string {
+  const m = /\.([a-z0-9]+)$/i.exec(p);
+  return m ? m[1].toLowerCase() : '';
+}
+
+/**
+ * Mint the blob URLs + CSS for a declaration set.
+ *
+ * @param decls   the fonts/assets the declaring file asked for
+ * @param basePath the DECLARING FILE's absolute fs path (resolution base)
+ * @param read    the bytes-read (fs)
+ */
+export async function mintThemeAssets(
+  decls: ThemeAssetDeclarations,
+  basePath: string,
+  read: AssetReader,
+): Promise<MintedThemeAssets> {
+  const urls: string[] = [];
+  const fontRules: string[] = [];
+  const varRules: string[] = [];
+
+  const mint = async (ref: string): Promise<string | null> => {
+    try {
+      const abs = resolvePath(basePath, ref);
+      const bytes = await read(abs);
+      const e = ext(abs);
+      const type = FONT_MIME[e] ?? IMAGE_MIME[e] ?? 'application/octet-stream';
+      const url = URL.createObjectURL(new Blob([bytes], { type }));
+      urls.push(url);
+      return url;
+    } catch {
+      return null; // degrade: the fallback stack / var() fallback answers
+    }
+  };
+
+  for (const f of decls.fonts ?? []) {
+    if (!f || typeof f.family !== 'string' || typeof f.src !== 'string') continue;
+    const url = await mint(f.src);
+    if (!url) continue;
+    const descriptors = [
+      `font-family: ${JSON.stringify(f.family)}`,
+      `src: url(${JSON.stringify(url)}) format(${JSON.stringify(ext(f.src) === 'woff2' ? 'woff2' : ext(f.src))})`,
+      ...(f.weight ? [`font-weight: ${f.weight}`] : []),
+      ...(f.style ? [`font-style: ${f.style}`] : []),
+      'font-display: swap',
+    ];
+    fontRules.push(`@font-face{${descriptors.join(';')}}`);
+  }
+
+  for (const [name, ref] of Object.entries(decls.assets ?? {})) {
+    if (!/^[a-z][a-z0-9-]*$/i.test(name) || typeof ref !== 'string') continue;
+    const url = await mint(ref);
+    if (!url) continue;
+    varRules.push(`--asset-${name}: url(${JSON.stringify(url)});`);
+  }
+
+  let revoked = false;
+  return {
+    fontFaceCss: fontRules.join('\n'),
+    assetVarsCss: varRules.length ? `.grove-root{${varRules.join('')}}` : '',
+    minted: urls.length,
+    revoke() {
+      if (revoked) return;
+      revoked = true;
+      for (const u of urls) URL.revokeObjectURL(u);
+    },
+  };
+}

package/src/lib/themeSelection.test.ts

@@ -0,0 +1,52 @@
+// The selection precedence (02-theme-contract §4), pinned as a decision table —
+// pure, so the whole cross-product of sources is cheap to assert. R3-308.
+import { describe, expect, it } from 'vitest';
+import { resolvePalette, resolvePolarity } from './themeSelection';
+import { preferredPolarity, THEMES } from '../data/themes';
+
+describe('resolvePalette — reader, else author, else default', () => {
+  it('a reader override wins over the author declaration', () => {
+    expect(resolvePalette({ reader: 'pixies', author: 'lotr' })).toBe('pixies');
+  });
+
+  it("a reader's explicit 'default' outranks a declaration — it is a choice, not an absence", () => {
+    expect(resolvePalette({ reader: 'default', author: 'lotr' })).toBe('default');
+  });
+
+  it('the author declaration is the default a reader falls into', () => {
+    expect(resolvePalette({ reader: null, author: 'family' })).toBe('family');
+  });
+
+  it('no reader, no author → default', () => {
+    expect(resolvePalette({})).toBe('default');
+    expect(resolvePalette({ reader: '', author: null })).toBe('default');
+  });
+});
+
+describe('resolvePolarity — reader, else host, else the palette’s own preference', () => {
+  it('a reader override wins over the host', () => {
+    expect(resolvePolarity({ reader: 'light', host: 'dark', preferred: 'dark' })).toBe('light');
+  });
+
+  it('the host drives polarity when the reader is silent — palette untouched (theme:read is polarity-only)', () => {
+    expect(resolvePolarity({ reader: null, host: 'light', preferred: 'dark' })).toBe('light');
+    expect(resolvePolarity({ reader: null, host: 'dark', preferred: 'light' })).toBe('dark');
+  });
+
+  it('no reader, no host → the palette’s preferred polarity', () => {
+    expect(resolvePolarity({ reader: null, host: null, preferred: 'light' })).toBe('light');
+  });
+
+  it('an unparseable stored override is silence, not a crash', () => {
+    expect(resolvePolarity({ reader: null, host: 'light', preferred: 'dark' })).toBe('light');
+  });
+});
+
+describe('the catalogue carries a preferred polarity for every theme (R3-308)', () => {
+  it('every theme declares one, and unknown ids fall back to dark', () => {
+    for (const t of THEMES) expect(['light', 'dark']).toContain(t.preferred);
+    expect(preferredPolarity('editorial')).toBe('dark');
+    expect(preferredPolarity('archive')).toBe('light');
+    expect(preferredPolarity('never-heard-of')).toBe('dark');
+  });
+});

package/src/lib/themeSelection.ts

@@ -0,0 +1,59 @@
+// Theme selection — the ONE resolution of who picks what a reader sees
+// (plans/grove-layouts-and-themes/02-theme-contract.mdx §4, R3-308).
+//
+// Two INDEPENDENT axes, three sources, stated once here so no surface re-derives
+// them (ways_of_working §5: one resolution entry point per concern):
+//
+//   palette  = reader override, else author declaration, else 'default'
+//   polarity = reader override, else host theme,        else the theme's own preferred
+//
+// The host has an opinion about POLARITY ONLY — it holds `theme:read` for exactly
+// that and nothing else, so it never appears in the palette chain. A reader's
+// choice outranks everyone and persists; an author's declaration is the default a
+// reader falls into, not a wall.
+//
+// PURE: takes already-read inputs, returns a decision. Where each input comes from
+// (localStorage, home-entry frontmatter, the host channel) is wiring, not policy,
+// and lives in the components.
+
+/** Light/dark — the axis that selects WITHIN a palette family. */
+export type Polarity = 'light' | 'dark';
+
+/** A palette family id — a `Theme['id']`, or any string a reader's override holds. */
+export type PaletteId = string;
+
+export interface PaletteInputs {
+  /** The reader's stored override (`grove:theme`), if any. */
+  reader?: PaletteId | null;
+  /** The author's `theme:` declaration on the home entry, if any. */
+  author?: PaletteId | null;
+}
+
+/**
+ * Resolve the palette. An empty/absent override is NOT an override — `''` would
+ * otherwise beat a real declaration while meaning nothing. `'default'` as a READER
+ * choice is meaningful ("the brand palette, even though this wiki declares another"),
+ * so any explicit reader value — `default` included — outranks the author.
+ */
+export function resolvePalette({ reader, author }: PaletteInputs): PaletteId {
+  if (reader) return reader;
+  if (author) return author;
+  return 'default';
+}
+
+export interface PolarityInputs {
+  /** The reader's stored override (`grove:appearance`), if any. */
+  reader?: Polarity | null;
+  /** The host's current theme, when the host has one (standalone: the channel's
+   *  initial — the host axis simply has no live source there). */
+  host?: Polarity | null;
+  /** The resolved palette's own preferred polarity. */
+  preferred: Polarity;
+}
+
+/** Resolve the polarity. Reader, then host, then the palette's own preference. */
+export function resolvePolarity({ reader, host, preferred }: PolarityInputs): Polarity {
+  if (reader === 'light' || reader === 'dark') return reader;
+  if (host === 'light' || host === 'dark') return host;
+  return preferred;
+}

package/src/mdxComponents.ts

@@ -6,6 +6,8 @@ import Lede from './components/Lede';
 import Infobox from './components/Infobox';
 import More from './components/More';
 import DocList from './components/DocList';
+import ThemeGallery from './components/ThemeGallery';
+import LayoutGallery from './components/LayoutGallery';
 import TagCloud from './components/TagCloud';
 import TagList from './components/TagList';
 import Directory from './components/Directory';
@@ -61,6 +63,8 @@ export const GROVE_MDX = {
   ChildPages,
   Timeline,
   FamilyTree,
+  ThemeGallery,
+  LayoutGallery,
   // Layout primitives — a `_layout.mdx` arranges the shell out of these around an
   // <Outlet/>, so the site chrome is content (see src/lib/layout.ts).
   Outlet,

package/viewer-manifest.schema.json

@@ -57,6 +57,43 @@
         "corpusTooling": { "type": "array", "items": { "type": "string" }, "description": "Keys a corpus's own tooling reads. The engine ignores them." },
         "passThrough": { "type": "boolean", "description": "Whether unknown keys are allowed (they are carried, unread). False makes the vocabulary closed." }
       }
+    },
+    "layouts": {
+      "type": "object",
+      "description": "The layout-starters catalogue (R3-309, bucket A): `_layout.mdx` starters under `content/_layouts/` a contributor or agent copies from. Keyed by starter id (= filename); `layoutRole` is the declared kind the entry and the file must agree on — the field existed in the sample layouts for a year with nothing reading it, and the catalogue is what gives it a job.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["layoutRole", "arranges", "ships", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "layoutRole": {
+            "enum": ["root", "section"],
+            "description": "`root` is an outermost shell (selects the nav arrangement); `section` nests under a root and wraps one folder."
+          },
+          "arranges": { "type": "string", "description": "The chrome the starter arranges around `<Outlet/>`." },
+          "ships": { "type": "boolean", "description": "Whether the starter file exists today (kept false for a catalogue entry whose file lands with a later item)." },
+          "summary": { "type": "string" }
+        }
+      }
+    },
+    "collections": {
+      "type": "object",
+      "description": "The collection-shapes catalogue (R3-309, bucket C): what a LIST of entries looks like. Behaviour lives here, not in a starter — an `_layout.mdx` cannot hold state, so infinite scroll is an engine component's literal prop, never a file you copy.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["ships", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "component": { "type": "string", "description": "The engine component the shape rides on (absent for shapes that are not component calls at all — a directory URL is one)." },
+          "props": {
+            "type": "object",
+            "description": "The literal attributes a corpus writes to select the shape. Expression props are dropped silently by the interpreter — every documented call must stay literal.",
+            "additionalProperties": { "type": "string" }
+          },
+          "ships": { "type": "boolean", "description": "Whether the shape renders today; a not-yet-shipping entry documents what lands with which item." },
+          "summary": { "type": "string" }
+        }
+      }
     }
   }
 }

package/viewer.manifest.json

@@ -36,7 +36,7 @@
         "title": "string?",
         "children": "node?"
       },
-      "summary": "An aside block with a kind (note / warning / \u2026)."
+      "summary": "An aside block with a kind (note / warning / …)."
     },
     "Lede": {
       "tier": "engine",
@@ -73,9 +73,11 @@
       "sanitizing": false,
       "props": {
         "tag": "string?",
-        "limit": "number?"
+        "limit": "number?",
+        "paginate": "'infinite'?",
+        "batch": "number?"
       },
-      "summary": "A queried list of entries \u2014 the generic index primitive."
+      "summary": "A queried list of entries — the generic index primitive. paginate=\"infinite\" windows it with a sentinel and a stated end (R3-314); the attribute must be a literal."
     },
     "TagCloud": {
       "tier": "engine",
@@ -177,7 +179,7 @@
       "overridable": true,
       "sanitizing": false,
       "props": {},
-      "summary": "The entry's own metadata line (updated, reading time, \u2026)."
+      "summary": "The entry's own metadata line (updated, reading time, …)."
     },
     "RecentlyUpdated": {
       "tier": "engine",
@@ -227,7 +229,7 @@
       "overridable": false,
       "sanitizing": false,
       "props": {},
-      "summary": "The layout chain's inward slot. NOT overridable \u2014 the chain's nesting is engine mechanics, and replacing it detaches every layer from the page it wraps."
+      "summary": "The layout chain's inward slot. NOT overridable — the chain's nesting is engine mechanics, and replacing it detaches every layer from the page it wraps."
     },
     "GroveNav": {
       "tier": "chrome",
@@ -249,19 +251,144 @@
       "sanitizing": false,
       "props": {},
       "summary": "The site footer."
+    },
+    "ThemeGallery": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "The themes gallery: one row per shipped theme, enumerated from this manifest — adding a theme adds a row with no edit to the entry."
+    },
+    "LayoutGallery": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "The layouts gallery: the starters, page variants and collection shapes grouped by their three mechanisms, enumerated from this manifest."
     }
   },
   "frontmatter": {
     "engine": [
       "site",
+      "theme",
       "layout",
       "view",
       "frame",
       "render",
       "nav",
       "order",
-      "tags"
+      "tags",
+      "cover"
     ],
     "passThrough": true
+  },
+  "themes": {
+    "default": {
+      "label": "immediately.run",
+      "preferred": "dark",
+      "ships": true,
+      "summary": "The brand applied to a reading surface — the baseline every other look is measured against."
+    },
+    "archive": {
+      "label": "Archive",
+      "preferred": "light",
+      "ships": true,
+      "summary": "Encyclopedic reference: dense, quiet, contents-forward. Source Serif 4 reading face."
+    },
+    "journal": {
+      "label": "Journal",
+      "preferred": "light",
+      "ships": true,
+      "summary": "A personal notebook or family record: warm, short measure, soft frame. Lora reading face."
+    },
+    "editorial": {
+      "label": "Editorial",
+      "preferred": "dark",
+      "ships": true,
+      "summary": "Loud on purpose — a zine, a gig listing, a release archive. Loud through weight and colour, not a new face."
+    }
+  },
+  "pageVariants": {
+    "doc": {
+      "key": "layout",
+      "value": "doc",
+      "ships": true,
+      "summary": "The default reference page: contents rail, floated infobox, backlink index."
+    },
+    "post": {
+      "key": "layout",
+      "value": "post",
+      "ships": true,
+      "summary": "One measured column, no rails — the long-form entry."
+    },
+    "full": {
+      "key": "layout",
+      "value": "full",
+      "ships": true,
+      "summary": "The widest measure; drawn on the directory board rather than its own."
+    },
+    "bare": {
+      "key": "frame",
+      "value": "none",
+      "ships": true,
+      "summary": "No chrome at all; the entry supplies its own."
+    }
+  },
+  "layouts": {
+    "shell": {
+      "layoutRole": "root",
+      "arranges": "nav · sidebar · content · footer",
+      "ships": true,
+      "summary": "The site shell as copyable content. `nav: side` by default; flip the frontmatter to `nav: top` and drop the `<GroveSidebar/>` line for the top-nav arrangement."
+    },
+    "section": {
+      "layoutRole": "section",
+      "arranges": "shared hero + <Outlet/> + siblings rail",
+      "ships": true,
+      "summary": "A folder frame: one shared header above every entry in a subtree, `<ChildPages/>` below. Nest it under a root shell."
+    },
+    "hero": {
+      "layoutRole": "root",
+      "arranges": "a full-bleed image band over top navigation, then a short grid",
+      "ships": true,
+      "summary": "A landing root: `nav: top`, a hero band, then `<DocList shape=\"grid\" limit=\"4\"/>`. The picture slot renders the link-graph lattice until `cover:` lands."
+    }
+  },
+  "collections": {
+    "feed": {
+      "component": "DocList",
+      "props": {
+        "shape": "feed"
+      },
+      "ships": true,
+      "summary": "A dated list of entries — title, date, lede."
+    },
+    "image-excerpt": {
+      "component": "DocList",
+      "props": {
+        "shape": "grid"
+      },
+      "ships": true,
+      "summary": "Cards with a picture slot and an excerpt. The slot holds the link-graph lattice until `cover:` lands (R3-313); it is not gated on it."
+    },
+    "timeline": {
+      "component": "Timeline",
+      "props": {},
+      "ships": true,
+      "summary": "Entries on a dated spine; already matches the reference archetype."
+    },
+    "directory": {
+      "ships": true,
+      "summary": "A folder URL with no `index.mdx` of its own — the generated listing. Not a component call: the mechanism is the URL itself."
+    },
+    "infinite-scroll": {
+      "component": "DocList",
+      "props": {
+        "paginate": "infinite",
+        "batch": "20"
+      },
+      "ships": true,
+      "summary": "The list that grows as you scroll: a windowed feed with a keyboard-actionable sentinel and a stated end. Behaviour like this can ONLY be an engine component's literal prop — never a starter file."
+    }
   }
 }