@iterant/site-runtime 3.4.0 → 3.5.0

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.4.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.5.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {

package/src/lib/database.ts

@@ -58,6 +58,31 @@ export type DatabaseQuery = {
 
 export type DatabaseRow = Record<string, string | number | null>;
 
+/**
+ * Where a rendered row came from, carried on the row so the visual editor can
+ * find the element again (epic DBX, decision DBX-D20). It rides a NON-enumerable
+ * `__db` slot: invisible to `JSON.stringify`, to `Object.keys`, and to every
+ * template that spreads or iterates the row, so nothing accidentally renders it.
+ */
+export type DbProvenance = {
+  table: string;
+  id: string;
+  /** Whether the published site shows this row. The preview channel projects it
+   *  per row (`_live`); a draft reads `false`. */
+  live: boolean;
+};
+
+/** The property that carries {@link DbProvenance}, hidden from enumeration. */
+const PROVENANCE_KEY = "__db";
+
+/** The attributes {@link dbAttrs} writes onto a DB-bound element. */
+export type DbAttrs = {
+  "data-db-table": string;
+  "data-db-row": string;
+  "data-db-col": string;
+  "data-db-draft"?: "";
+};
+
 export type DatabaseResult = {
   rows: DatabaseRow[];
   /** Every row matching the query, not just this page. */
@@ -151,5 +176,72 @@ export async function readDatabase(
   if (!Array.isArray(page.rows)) {
     return warn(`"${table}" answered without rows`, body);
   }
-  return { rows: page.rows, total: Number(page.total ?? page.rows.length) };
+  return {
+    rows: page.rows.map((row) => withProvenance(row, table)),
+    total: Number(page.total ?? page.rows.length),
+  };
+}
+
+/**
+ * Attach {@link DbProvenance} to a row that carries a system `_id`.
+ *
+ * The preview-read channel returns `_id` and a computed `_live` flag; the public
+ * production read (C6) is published-only and carries neither, so this leaves a
+ * production row untouched. The `_live` flag is lifted OFF the row into the
+ * hidden slot so no template can render it; `_id` stays where a `systemColumns`
+ * grant may legitimately want it. The slot is non-enumerable, so a row that
+ * spreads or serializes looks exactly as it did before.
+ */
+function withProvenance(row: DatabaseRow, table: string): DatabaseRow {
+  const id = row._id;
+  if (id === undefined || id === null) return row;
+  const { _live, ...rest } = row;
+  const provenance: DbProvenance = {
+    table,
+    id: String(id),
+    live: _live === undefined ? true : _live !== 0,
+  };
+  Object.defineProperty(rest, PROVENANCE_KEY, {
+    value: provenance,
+    enumerable: false,
+    writable: false,
+    configurable: true,
+  });
+  return rest;
+}
+
+function provenanceOf(row: DatabaseRow): DbProvenance | undefined {
+  return (row as { [PROVENANCE_KEY]?: DbProvenance })[PROVENANCE_KEY];
+}
+
+/**
+ * The `data-db-*` attributes that make a DB-bound element self-describing, spread
+ * onto the element where the value is interpolated:
+ *
+ * ```astro
+ * <h1 {...dbAttrs(article, "title")}>{article.title}</h1>
+ * ```
+ *
+ * The visual editor reads these to map a click back to a table, row, and column
+ * (dbx-31). A draft row (its `_live` is false) also gets `data-db-draft`, which
+ * the preview marks so a screenshot cannot be mistaken for the live page.
+ *
+ * Returns `{}` in a production build (`import.meta.env.PROD`) and when the row
+ * carries no provenance, so published HTML ships with no annotations and no row
+ * ids. Preview only, by default (fork F1).
+ */
+export function dbAttrs(
+  row: DatabaseRow,
+  column: string,
+): DbAttrs | Record<string, never> {
+  if (import.meta.env.PROD) return {};
+  const provenance = provenanceOf(row);
+  if (!provenance) return {};
+  const attrs: DbAttrs = {
+    "data-db-table": provenance.table,
+    "data-db-row": provenance.id,
+    "data-db-col": column,
+  };
+  if (provenance.live === false) attrs["data-db-draft"] = "";
+  return attrs;
 }

package/src/lib/locales.ts

@@ -25,9 +25,11 @@ export const DEFAULT_LOCALE = "en";
  * `chrome.pt-br` → {base:"chrome", locale:"pt-br"}. Base names never contain
  * dots, so any well-formed lowercased locale suffix IS a sibling id.
  *
- * KEEP IN SYNC with `apps/agent-mvp/src/locales.ts#parseEntryId` — the agent
- * writes the sibling ids the site reads back (out-of-workspace duplication,
- * same pattern as the special-input mirrors).
+ * The agent-side counterpart is
+ * `apps/agent-flue/src/product/localization.ts#parseEntryId`: the agent writes
+ * the sibling ids the site reads back (out-of-workspace duplication). KEEP THE
+ * LOCALE SEGMENT GRAMMAR IN SYNC with its LOCALE_SEGMENT_PATTERN; the two
+ * differ only on ids whose suffix fails that grammar.
  */
 export function parseEntryId(id: string): { base: string; locale?: string } {
   const dot = id.indexOf(".");
@@ -42,8 +44,8 @@ export function parseEntryId(id: string): { base: string; locale?: string } {
  * Canonical BCP-47 casing for a locale (`pt-br` → `pt-BR`, `ES` → `es`):
  * language subtag lowercased, 4-alpha script subtags Titlecased, other
  * subtags uppercased. Files/routes use the lowercased segment; this casing is
- * for the `<html lang>` attribute and hreflang values (starter 2.9.0). KEEP IN
- * SYNC with `apps/agent-mvp/src/locales.ts#normalizeBcp47`.
+ * for the `<html lang>` attribute and hreflang values (starter 2.9.0). This is
+ * the single implementation; the agent side never renders lang attributes.
  */
 export function normalizeBcp47(locale: string): string {
   const raw = locale.trim().replace(/_/g, "-");