@immediately-run/grove 0.1.1

package/viewer-manifest.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://immediately.run/viewer-manifest.schema.json",
+  "title": "immediately.run viewer component manifest",
+  "description": "The component vocabulary a directory-as-content VIEWER declares. Two-way surface (PLATFORM_LAYERING_SPEC §5 target 3): a corpus checker reads it to know which components a corpus may use, and a thin shell composing the viewer as a library (§1.1 M3) reads it to know which components it may override, with what props. The FORMAT is viewer-generic — a Lodestar manifest with a node/edge vocabulary validates through this same schema; only the entries are per-viewer.",
+  "type": "object",
+  "required": ["schemaVersion", "viewer", "components"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "viewer": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "description": "The package name a shell imports." },
+        "kind": { "type": "string", "description": "The content kind this viewer renders (`wiki`, `board`, …) — display and discovery only; it confers nothing." },
+        "task": { "type": "string", "description": "The task CONTRACT this viewer provides, matching package.json `immediately.run.provides`." }
+      }
+    },
+    "components": {
+      "type": "object",
+      "description": "Component name → its contract. A name absent here is INTERNAL: a corpus using it is flagged, and a shell overriding it fails visibly.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["tier", "overridable"],
+        "additionalProperties": false,
+        "properties": {
+          "tier": {
+            "enum": ["engine", "chrome", "corpus"],
+            "description": "`engine` renders any corpus and holds no opinion about its subject; `chrome` is site furniture a layout arranges; `corpus` is furniture encoding ONE corpus's frontmatter conventions, declared by that corpus rather than the engine (ENGINE_BOUNDARY §3)."
+          },
+          "overridable": {
+            "type": "boolean",
+            "description": "Whether a library-composing shell may replace it. False for components whose behaviour is engine mechanics rather than presentation."
+          },
+          "sanitizing": {
+            "type": "boolean",
+            "description": "Whether this component is a sanitizing wrapper on the interpreter path. An override of a sanitizing component inherits the obligation — that is why the flag is on the contract and not in a comment."
+          },
+          "props": {
+            "type": "object",
+            "description": "Prop name → a short type string (`string?`, `number?`, `node?`, `string[]?`). Documentation for an overriding shell, not a runtime check.",
+            "additionalProperties": { "type": "string" }
+          },
+          "summary": { "type": "string" }
+        }
+      }
+    },
+    "frontmatter": {
+      "type": "object",
+      "description": "Frontmatter key OWNERSHIP (PLATFORM_LAYERING §5 target 1). Each side validates the keys it owns; pass-through is what keeps a foreign corpus with its own vocabulary renderable.",
+      "additionalProperties": false,
+      "properties": {
+        "engine": { "type": "array", "items": { "type": "string" }, "description": "Keys the ENGINE reads. Changing one changes rendering." },
+        "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." }
+      }
+    }
+  }
+}

package/viewer.manifest.json

@@ -0,0 +1,267 @@
+{
+  "$schema": "./viewer-manifest.schema.json",
+  "schemaVersion": 1,
+  "viewer": {
+    "name": "@immediately-run/grove",
+    "kind": "wiki",
+    "task": "open-wiki"
+  },
+  "components": {
+    "a": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "href": "string?",
+        "children": "node?"
+      },
+      "summary": "Wiki-link resolver: renders the resolved / broken / self states for an in-corpus href."
+    },
+    "img": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "src": "string?",
+        "alt": "string?"
+      },
+      "summary": "Resolves a mount-relative asset off the filesystem."
+    },
+    "Callout": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "kind": "string?",
+        "title": "string?",
+        "children": "node?"
+      },
+      "summary": "An aside block with a kind (note / warning / \u2026)."
+    },
+    "Lede": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "children": "node?"
+      },
+      "summary": "The opening paragraph, set apart typographically."
+    },
+    "Infobox": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "title": "string?",
+        "children": "node?"
+      },
+      "summary": "The boxed summary panel a wiki entry carries beside its lede."
+    },
+    "More": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "href": "string?",
+        "children": "node?"
+      },
+      "summary": "A 'read more' pointer to a related entry."
+    },
+    "DocList": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "tag": "string?",
+        "limit": "number?"
+      },
+      "summary": "A queried list of entries \u2014 the generic index primitive."
+    },
+    "TagCloud": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "limit": "number?"
+      },
+      "summary": "Every tag in the corpus, weighted by use."
+    },
+    "TagList": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "tags": "string[]?"
+      },
+      "summary": "The tags of one entry, as links to their indexes."
+    },
+    "Directory": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "path": "string?"
+      },
+      "summary": "The entries under one corpus directory."
+    },
+    "DirectoryList": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "path": "string?",
+        "title": "string?",
+        "columns": "string?",
+        "sort": "string?",
+        "hidden": "boolean?"
+      },
+      "summary": "A folder listing as a table, with metadata columns chosen by `columns` and narrowed to those the rows actually carry."
+    },
+    "Quote": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "cite": "string?",
+        "children": "node?"
+      },
+      "summary": "A pull quote with an optional citation."
+    },
+    "KeyValue": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "children": "node?"
+      },
+      "summary": "A definition-list row for infobox-style facts."
+    },
+    "Kbd": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "children": "node?"
+      },
+      "summary": "A keyboard key."
+    },
+    "Toc": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "depth": "number?"
+      },
+      "summary": "The table of contents derived from the entry's heading anchors."
+    },
+    "TableOfContents": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "entryKey": "string?",
+        "title": "string?",
+        "className": "string?"
+      },
+      "summary": "The on-this-page heading list, which keeps the active entry in view as the reader scrolls."
+    },
+    "Backlinks": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "Entries linking to this one."
+    },
+    "PageMeta": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "The entry's own metadata line (updated, reading time, \u2026)."
+    },
+    "RecentlyUpdated": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "limit": "number?"
+      },
+      "summary": "The most recently updated entries."
+    },
+    "DocsByTag": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "tag": "string?"
+      },
+      "summary": "Entries grouped under one tag."
+    },
+    "ChildPages": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "The entries nested under this one."
+    },
+    "Timeline": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "children": "node?"
+      },
+      "summary": "A dated sequence of entries or events."
+    },
+    "FamilyTree": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {
+        "children": "node?"
+      },
+      "summary": "A relationship graph rendered from frontmatter links."
+    },
+    "Outlet": {
+      "tier": "engine",
+      "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."
+    },
+    "GroveNav": {
+      "tier": "chrome",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "Top/side navigation. Reads the shell context, so an override must too (or render its own)."
+    },
+    "GroveSidebar": {
+      "tier": "chrome",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "The corpus tree sidebar."
+    },
+    "GroveFooter": {
+      "tier": "chrome",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "The site footer."
+    }
+  },
+  "frontmatter": {
+    "engine": [
+      "site",
+      "layout",
+      "view",
+      "frame",
+      "render",
+      "nav",
+      "order",
+      "tags"
+    ],
+    "passThrough": true
+  }
+}