@contractspec/lib.presentation-runtime-core 3.8.3 → 3.9.0

package/dist/browser/index.js

@@ -517,9 +517,88 @@ function withPresentationMetroAliases(config, opts = {}) {
   };
   return config;
 }
+var tech_presentation_runtime_DocBlocks = [
+  {
+    id: "docs.tech.presentation-runtime",
+    title: "Presentation Runtime",
+    summary: "Cross-platform runtime for list pages, presentation flows, and headless ContractSpec tables.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/presentation-runtime",
+    tags: ["tech", "presentation-runtime"],
+    body: `## Presentation Runtime
+
+Cross-platform runtime for list pages, presentation flows, and headless ContractSpec tables.
+
+### Packages
+
+- \`@contractspec/lib.presentation-runtime-core\`: shared state/types for URL state, list coordination, and headless table controllers
+- \`@contractspec/lib.presentation-runtime-react\`: React hooks (web/native-compatible API)
+- \`@contractspec/lib.presentation-runtime-react-native\`: Native entrypoint (re-exports the shared React table hooks and keeps native form/list helpers)
+
+### Next.js config helper
+
+\`\`\`ts
+// next.config.mjs
+import { withPresentationNextAliases } from '@contractspec/lib.presentation-runtime-core/next';
+
+const nextConfig = {
+  webpack: (config) => withPresentationNextAliases(config),
+};
+
+export default nextConfig;
+\`\`\`
+
+### Metro config helper
+
+\`\`\`js
+// metro.config.js (CJS)
+const { getDefaultConfig } = require('expo/metro-config');
+const {
+  withPresentationMetroAliases,
+} = require('@contractspec/lib.presentation-runtime-core/src/metro.cjs');
+
+const projectRoot = __dirname;
+const config = getDefaultConfig(projectRoot);
+
+module.exports = withPresentationMetroAliases(config);
+\`\`\`
+
+### React hooks
+
+- \`useListCoordinator\`: URL + RHF + derived variables (no fetching)
+- \`usePresentationController\`: Same plus \`fetcher\` integration
+- \`useContractTable\`: headless TanStack-backed controller for sorting, pagination, selection, visibility, pinning, resizing, and expansion
+- \`useDataViewTable\`: adapter that maps \`DataViewSpec\` table contracts onto the generic controller
+- \`DataViewRenderer\` (design-system): render \`DataViewSpec\` projections (\`list\`, \`table\`, \`detail\`, \`grid\`) using shared UI atoms
+
+Both list hooks accept a \`useUrlState\` adapter. On web, use \`useListUrlState\` (design-system) or a Next adapter.
+
+### Table layering
+
+- \`contracts-spec\`: declarative table contract (\`DataViewTableConfig\`)
+- \`presentation-runtime-*\`: headless controller state and TanStack integration
+- \`ui-kit\` / \`ui-kit-web\`: platform renderers that consume controller output
+- \`design-system\`: opinionated \`DataTable\`, \`DataViewTable\`, \`ApprovalQueue\`, and \`ListTablePage\`
+
+### KYC molecules (bundle)
+
+- \`ComplianceBadge\` in \`@contractspec/bundle.strit/presentation/components/kyc\` renders a status badge for KYC/compliance snapshots. It accepts a \`state\` (missing_core | incomplete | complete | expiring | unknown) and optional localized \`labels\`. Prefer consuming apps to pass translated labels (e.g., via \`useT('appPlatformAdmin')\`).
+
+### Markdown routes and llms.txt
+
+- Each web app exposes \`/llms\` (and \`/llms.txt\`, \`/llms.md\`) via rewrites. See [llmstxt.org](https://llmstxt.org/).
+- Catch‑all markdown handler lives at \`app/[...slug].md/route.ts\`. It resolves a page descriptor from \`app/.presentations.manifest.json\` and renders via the \`presentations.v2\` engine (target: \`markdown\`).
+- Per‑page companion convention: add \`app/<route>/ai.ts\` exporting a \`PresentationSpec\`.
+- Build‑time tool: \`tools/generate-presentations-manifest.mjs <app-root>\` populates the manifest.
+- CI check: \`bunllms:check\` verifies coverage (% of pages with descriptors) and fails if below threshold.
+`
+  }
+];
 export {
   withPresentationNextAliases,
   withPresentationMetroAliases,
+  tech_presentation_runtime_DocBlocks,
   formatVisualizationValue,
   createVisualizationModel,
   createEmptyTableState,

package/dist/browser/transform-engine.js

@@ -0,0 +1,314 @@
+// src/transform-engine.markdown.ts
+import TurndownService from "turndown";
+function renderTextNode(node) {
+  const text = node.text ?? "";
+  if (!node.marks || node.marks.length === 0)
+    return text;
+  return node.marks.reduce((acc, mark) => {
+    switch (mark.type) {
+      case "bold":
+        return `**${acc}**`;
+      case "italic":
+        return `*${acc}*`;
+      case "underline":
+        return `__${acc}__`;
+      case "strike":
+        return `~~${acc}~~`;
+      case "code":
+        return `\`${acc}\``;
+      case "link": {
+        const href = mark.attrs?.href ?? "";
+        return href ? `[${acc}](${href})` : acc;
+      }
+      default:
+        return acc;
+    }
+  }, text);
+}
+function renderInline(nodes) {
+  if (!nodes?.length)
+    return "";
+  return nodes.map((child) => renderNode(child)).join("");
+}
+function renderList(nodes, ordered = false) {
+  if (!nodes?.length)
+    return "";
+  let counter = 1;
+  return nodes.map((item) => {
+    const body = renderInline(item.content ?? []);
+    if (!body)
+      return "";
+    const prefix = ordered ? `${counter++}. ` : "- ";
+    return `${prefix}${body}`;
+  }).filter(Boolean).join(`
+`);
+}
+function renderNode(node) {
+  switch (node.type) {
+    case "doc":
+      return renderInline(node.content);
+    case "paragraph": {
+      const text = renderInline(node.content);
+      return text.trim().length ? text : "";
+    }
+    case "heading": {
+      const levelAttr = node.attrs?.level;
+      const levelVal = typeof levelAttr === "number" ? levelAttr : 1;
+      const level = Math.min(Math.max(levelVal, 1), 6);
+      return `${"#".repeat(level)} ${renderInline(node.content)}`.trim();
+    }
+    case "bullet_list":
+      return renderList(node.content, false);
+    case "ordered_list":
+      return renderList(node.content, true);
+    case "list_item":
+      return renderInline(node.content);
+    case "blockquote": {
+      const body = renderInline(node.content);
+      return body.split(`
+`).map((line) => `> ${line}`).join(`
+`);
+    }
+    case "code_block": {
+      const body = renderInline(node.content);
+      return body ? `\`\`\`
+${body}
+\`\`\`` : "";
+    }
+    case "horizontal_rule":
+      return "---";
+    case "hard_break":
+      return `
+`;
+    case "text":
+      return renderTextNode(node);
+    default:
+      if (node.text)
+        return renderTextNode(node);
+      return "";
+  }
+}
+function createMarkdownTurndownService() {
+  const turndownService = new TurndownService({
+    headingStyle: "atx",
+    codeBlockStyle: "fenced",
+    bulletListMarker: "-"
+  });
+  turndownService.addRule("link", {
+    filter: "a",
+    replacement: (content, node) => {
+      const candidate = node;
+      const href = candidate.getAttribute?.("href") ?? (typeof candidate.href === "string" ? candidate.href : "");
+      if (href && content) {
+        return `[${content}](${href})`;
+      }
+      return content || "";
+    }
+  });
+  return turndownService;
+}
+var defaultTurndown = createMarkdownTurndownService();
+function htmlToMarkdown(html) {
+  return defaultTurndown.turndown(html);
+}
+function blockNoteToMarkdown(docJson) {
+  if (typeof docJson === "string")
+    return docJson;
+  if (docJson && typeof docJson === "object" && "html" in docJson) {
+    const html = String(docJson.html);
+    return htmlToMarkdown(html);
+  }
+  const root = docJson;
+  if (root?.type === "doc" || root?.content) {
+    const blocks = (root.content ?? []).map((node) => renderNode(node)).filter(Boolean);
+    return blocks.join(`
+
+`).trim();
+  }
+  try {
+    return JSON.stringify(docJson, null, 2);
+  } catch {
+    return String(docJson);
+  }
+}
+
+// src/transform-engine.ts
+import { schemaToMarkdown } from "@contractspec/lib.contracts-spec/schema-to-markdown";
+function applyPii(desc, obj) {
+  let clone;
+  try {
+    clone = JSON.parse(JSON.stringify(obj));
+  } catch {
+    clone = obj;
+  }
+  const paths = desc.policy?.pii ?? [];
+  const setAtPath = (root, path) => {
+    const segments = path.replace(/^\//, "").replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+    let current = root;
+    for (let i = 0;i < segments.length - 1; i++) {
+      const key = segments[i];
+      if (!key || !current || typeof current !== "object" || !(key in current)) {
+        return;
+      }
+      current = current[key];
+    }
+    const last = segments[segments.length - 1];
+    if (current && typeof current === "object" && last && last in current) {
+      current[last] = "[REDACTED]";
+    }
+  };
+  for (const path of paths) {
+    setAtPath(clone, path);
+  }
+  return clone;
+}
+
+class TransformEngine {
+  renderers = new Map;
+  validators = [];
+  register(renderer) {
+    const renderers = this.renderers.get(renderer.target) ?? [];
+    renderers.push(renderer);
+    this.renderers.set(renderer.target, renderers);
+    return this;
+  }
+  prependRegister(renderer) {
+    const renderers = this.renderers.get(renderer.target) ?? [];
+    renderers.unshift(renderer);
+    this.renderers.set(renderer.target, renderers);
+    return this;
+  }
+  addValidator(validator) {
+    this.validators.push(validator);
+    return this;
+  }
+  async render(target, desc, ctx) {
+    if (!desc.targets.includes(target)) {
+      throw new Error(`Target ${target} not declared for ${desc.meta.key}.v${desc.meta.version}`);
+    }
+    for (const validator of this.validators) {
+      await validator.validate(desc, target, ctx);
+    }
+    const renderers = this.renderers.get(target) ?? [];
+    for (const renderer of renderers) {
+      try {
+        return await renderer.render(desc, ctx);
+      } catch {}
+    }
+    throw new Error(`No renderer available for ${target}`);
+  }
+}
+function createDefaultTransformEngine() {
+  const engine = new TransformEngine;
+  engine.register({
+    target: "markdown",
+    async render(desc, ctx) {
+      let data = ctx?.data;
+      if (!data && ctx?.fetchData) {
+        data = await ctx.fetchData();
+      }
+      if (desc.source.type === "component" && desc.source.props && data !== undefined) {
+        const isArray = Array.isArray(data);
+        const isSimpleObject = !isArray && typeof data === "object" && data !== null && !Object.values(data).some((value) => Array.isArray(value) || typeof value === "object" && value !== null);
+        if (isArray || isSimpleObject) {
+          return {
+            mimeType: "text/markdown",
+            body: schemaToMarkdown(desc.source.props, data, {
+              title: desc.meta.description ?? desc.meta.key,
+              description: `${desc.meta.key} v${desc.meta.version}`
+            })
+          };
+        }
+        throw new Error(`Complex data structure for ${desc.meta.key} - expecting custom renderer`);
+      }
+      if (desc.source.type === "blocknotejs") {
+        const redacted = applyPii(desc, {
+          text: blockNoteToMarkdown(desc.source.docJson)
+        });
+        return {
+          mimeType: "text/markdown",
+          body: String(redacted.text ?? "")
+        };
+      }
+      if (desc.source.type === "component" && data !== undefined) {
+        throw new Error(`No schema (source.props) available for ${desc.meta.key} - expecting custom renderer`);
+      }
+      if (desc.source.type !== "component") {
+        throw new Error("unsupported");
+      }
+      const header = `# ${desc.meta.key} v${desc.meta.version}`;
+      const about = desc.meta.description ? `
+
+${desc.meta.description}` : "";
+      const tags = desc.meta.tags && desc.meta.tags.length ? `
+
+Tags: ${desc.meta.tags.join(", ")}` : "";
+      const owners = desc.meta.owners && desc.meta.owners.length ? `
+
+Owners: ${desc.meta.owners.join(", ")}` : "";
+      const component = `
+
+Component: \`${desc.source.componentKey}\``;
+      const policy = desc.policy?.pii?.length ? `
+
+Redacted paths: ${desc.policy.pii.map((path) => `\`${path}\``).join(", ")}` : "";
+      return {
+        mimeType: "text/markdown",
+        body: `${header}${about}${tags}${owners}${component}${policy}`
+      };
+    }
+  });
+  engine.register({
+    target: "application/json",
+    async render(desc) {
+      const payload = applyPii(desc, { meta: desc.meta, source: desc.source });
+      let body;
+      try {
+        body = JSON.stringify(payload, null, 2);
+      } catch {
+        body = JSON.stringify({
+          meta: { key: desc.meta.key, version: desc.meta.version },
+          source: "[non-serializable]"
+        }, null, 2);
+      }
+      return { mimeType: "application/json", body };
+    }
+  });
+  engine.register({
+    target: "application/xml",
+    async render(desc) {
+      const payload = applyPii(desc, { meta: desc.meta, source: desc.source });
+      let json;
+      try {
+        json = JSON.stringify(payload);
+      } catch {
+        json = JSON.stringify({
+          meta: { key: desc.meta.key, version: desc.meta.version },
+          source: "[non-serializable]"
+        });
+      }
+      return {
+        mimeType: "application/xml",
+        body: `<presentation name="${desc.meta.key}" version="${desc.meta.version}"><json>${encodeURIComponent(json)}</json></presentation>`
+      };
+    }
+  });
+  return engine;
+}
+function registerBasicValidation(engine) {
+  engine.addValidator({
+    validate(desc) {
+      if (!desc.meta.description || desc.meta.description.length < 3) {
+        throw new Error(`Presentation ${desc.meta.key}.v${desc.meta.version} missing meta.description`);
+      }
+    }
+  });
+  return engine;
+}
+export {
+  registerBasicValidation,
+  htmlToMarkdown,
+  createDefaultTransformEngine,
+  blockNoteToMarkdown,
+  TransformEngine
+};

package/dist/browser/transform-engine.markdown.js

@@ -0,0 +1,138 @@
+// src/transform-engine.markdown.ts
+import TurndownService from "turndown";
+function renderTextNode(node) {
+  const text = node.text ?? "";
+  if (!node.marks || node.marks.length === 0)
+    return text;
+  return node.marks.reduce((acc, mark) => {
+    switch (mark.type) {
+      case "bold":
+        return `**${acc}**`;
+      case "italic":
+        return `*${acc}*`;
+      case "underline":
+        return `__${acc}__`;
+      case "strike":
+        return `~~${acc}~~`;
+      case "code":
+        return `\`${acc}\``;
+      case "link": {
+        const href = mark.attrs?.href ?? "";
+        return href ? `[${acc}](${href})` : acc;
+      }
+      default:
+        return acc;
+    }
+  }, text);
+}
+function renderInline(nodes) {
+  if (!nodes?.length)
+    return "";
+  return nodes.map((child) => renderNode(child)).join("");
+}
+function renderList(nodes, ordered = false) {
+  if (!nodes?.length)
+    return "";
+  let counter = 1;
+  return nodes.map((item) => {
+    const body = renderInline(item.content ?? []);
+    if (!body)
+      return "";
+    const prefix = ordered ? `${counter++}. ` : "- ";
+    return `${prefix}${body}`;
+  }).filter(Boolean).join(`
+`);
+}
+function renderNode(node) {
+  switch (node.type) {
+    case "doc":
+      return renderInline(node.content);
+    case "paragraph": {
+      const text = renderInline(node.content);
+      return text.trim().length ? text : "";
+    }
+    case "heading": {
+      const levelAttr = node.attrs?.level;
+      const levelVal = typeof levelAttr === "number" ? levelAttr : 1;
+      const level = Math.min(Math.max(levelVal, 1), 6);
+      return `${"#".repeat(level)} ${renderInline(node.content)}`.trim();
+    }
+    case "bullet_list":
+      return renderList(node.content, false);
+    case "ordered_list":
+      return renderList(node.content, true);
+    case "list_item":
+      return renderInline(node.content);
+    case "blockquote": {
+      const body = renderInline(node.content);
+      return body.split(`
+`).map((line) => `> ${line}`).join(`
+`);
+    }
+    case "code_block": {
+      const body = renderInline(node.content);
+      return body ? `\`\`\`
+${body}
+\`\`\`` : "";
+    }
+    case "horizontal_rule":
+      return "---";
+    case "hard_break":
+      return `
+`;
+    case "text":
+      return renderTextNode(node);
+    default:
+      if (node.text)
+        return renderTextNode(node);
+      return "";
+  }
+}
+function createMarkdownTurndownService() {
+  const turndownService = new TurndownService({
+    headingStyle: "atx",
+    codeBlockStyle: "fenced",
+    bulletListMarker: "-"
+  });
+  turndownService.addRule("link", {
+    filter: "a",
+    replacement: (content, node) => {
+      const candidate = node;
+      const href = candidate.getAttribute?.("href") ?? (typeof candidate.href === "string" ? candidate.href : "");
+      if (href && content) {
+        return `[${content}](${href})`;
+      }
+      return content || "";
+    }
+  });
+  return turndownService;
+}
+var defaultTurndown = createMarkdownTurndownService();
+function htmlToMarkdown(html) {
+  return defaultTurndown.turndown(html);
+}
+function blockNoteToMarkdown(docJson) {
+  if (typeof docJson === "string")
+    return docJson;
+  if (docJson && typeof docJson === "object" && "html" in docJson) {
+    const html = String(docJson.html);
+    return htmlToMarkdown(html);
+  }
+  const root = docJson;
+  if (root?.type === "doc" || root?.content) {
+    const blocks = (root.content ?? []).map((node) => renderNode(node)).filter(Boolean);
+    return blocks.join(`
+
+`).trim();
+  }
+  try {
+    return JSON.stringify(docJson, null, 2);
+  } catch {
+    return String(docJson);
+  }
+}
+export {
+  htmlToMarkdown,
+  createMarkdownTurndownService,
+  blockNoteToMarkdown
+};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
 export interface ListState<TFilters extends Record<string, unknown>> {
     q: string;
     page: number;
@@ -26,3 +27,4 @@ export type MetroAliasOptions = NextAliasOptions & {
     monorepoRoot?: string;
 };
 export declare function withPresentationMetroAliases(config: any, opts?: MetroAliasOptions): any;
+export declare const tech_presentation_runtime_DocBlocks: DocBlock[];

package/dist/index.js

@@ -518,9 +518,88 @@ function withPresentationMetroAliases(config, opts = {}) {
   };
   return config;
 }
+var tech_presentation_runtime_DocBlocks = [
+  {
+    id: "docs.tech.presentation-runtime",
+    title: "Presentation Runtime",
+    summary: "Cross-platform runtime for list pages, presentation flows, and headless ContractSpec tables.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/presentation-runtime",
+    tags: ["tech", "presentation-runtime"],
+    body: `## Presentation Runtime
+
+Cross-platform runtime for list pages, presentation flows, and headless ContractSpec tables.
+
+### Packages
+
+- \`@contractspec/lib.presentation-runtime-core\`: shared state/types for URL state, list coordination, and headless table controllers
+- \`@contractspec/lib.presentation-runtime-react\`: React hooks (web/native-compatible API)
+- \`@contractspec/lib.presentation-runtime-react-native\`: Native entrypoint (re-exports the shared React table hooks and keeps native form/list helpers)
+
+### Next.js config helper
+
+\`\`\`ts
+// next.config.mjs
+import { withPresentationNextAliases } from '@contractspec/lib.presentation-runtime-core/next';
+
+const nextConfig = {
+  webpack: (config) => withPresentationNextAliases(config),
+};
+
+export default nextConfig;
+\`\`\`
+
+### Metro config helper
+
+\`\`\`js
+// metro.config.js (CJS)
+const { getDefaultConfig } = require('expo/metro-config');
+const {
+  withPresentationMetroAliases,
+} = require('@contractspec/lib.presentation-runtime-core/src/metro.cjs');
+
+const projectRoot = __dirname;
+const config = getDefaultConfig(projectRoot);
+
+module.exports = withPresentationMetroAliases(config);
+\`\`\`
+
+### React hooks
+
+- \`useListCoordinator\`: URL + RHF + derived variables (no fetching)
+- \`usePresentationController\`: Same plus \`fetcher\` integration
+- \`useContractTable\`: headless TanStack-backed controller for sorting, pagination, selection, visibility, pinning, resizing, and expansion
+- \`useDataViewTable\`: adapter that maps \`DataViewSpec\` table contracts onto the generic controller
+- \`DataViewRenderer\` (design-system): render \`DataViewSpec\` projections (\`list\`, \`table\`, \`detail\`, \`grid\`) using shared UI atoms
+
+Both list hooks accept a \`useUrlState\` adapter. On web, use \`useListUrlState\` (design-system) or a Next adapter.
+
+### Table layering
+
+- \`contracts-spec\`: declarative table contract (\`DataViewTableConfig\`)
+- \`presentation-runtime-*\`: headless controller state and TanStack integration
+- \`ui-kit\` / \`ui-kit-web\`: platform renderers that consume controller output
+- \`design-system\`: opinionated \`DataTable\`, \`DataViewTable\`, \`ApprovalQueue\`, and \`ListTablePage\`
+
+### KYC molecules (bundle)
+
+- \`ComplianceBadge\` in \`@contractspec/bundle.strit/presentation/components/kyc\` renders a status badge for KYC/compliance snapshots. It accepts a \`state\` (missing_core | incomplete | complete | expiring | unknown) and optional localized \`labels\`. Prefer consuming apps to pass translated labels (e.g., via \`useT('appPlatformAdmin')\`).
+
+### Markdown routes and llms.txt
+
+- Each web app exposes \`/llms\` (and \`/llms.txt\`, \`/llms.md\`) via rewrites. See [llmstxt.org](https://llmstxt.org/).
+- Catch\u2011all markdown handler lives at \`app/[...slug].md/route.ts\`. It resolves a page descriptor from \`app/.presentations.manifest.json\` and renders via the \`presentations.v2\` engine (target: \`markdown\`).
+- Per\u2011page companion convention: add \`app/<route>/ai.ts\` exporting a \`PresentationSpec\`.
+- Build\u2011time tool: \`tools/generate-presentations-manifest.mjs <app-root>\` populates the manifest.
+- CI check: \`bunllms:check\` verifies coverage (% of pages with descriptors) and fails if below threshold.
+`
+  }
+];
 export {
   withPresentationNextAliases,
   withPresentationMetroAliases,
+  tech_presentation_runtime_DocBlocks,
   formatVisualizationValue,
   createVisualizationModel,
   createEmptyTableState,