@synap-core/sdk 1.4.0 → 1.5.1

package/src/connect/hub-types.ts

@@ -0,0 +1,271 @@
+/**
+ * Wire shapes of the Hub REST doors `createPodClient`'s typed methods read.
+ *
+ * DRIFT RISK: hand-written from synap-backend main (2026-10-22), each from the
+ * route itself, never from `@synap-core/hub-rest-client` alone:
+ *  - entities: `routers/hub-protocol/rest/entities.ts` (`GET /entities`,
+ *    `GET /entities/:id` → `entityToWire`, `_codecs/entity.ts`
+ *    `WireEntitySchema`; `GET /entities/:id/connections` → `relations.ts`
+ *    `getConnections`, `services/object-graph/entity-connections.ts`);
+ *  - documents: `rest/documents.ts` `GET /documents/:id` →
+ *    `services/document-patch/read-document.ts` `projectAgentDocument`;
+ *  - focus sessions: `rest/focus-sessions.ts` `GET /focus-sessions` (raw rows +
+ *    `triage` + `kind`), slots `services/focus-sessions/update-session.ts`
+ *    `expectedOutputWireSchema`;
+ *  - files: `rest/entities.ts` `GET /files/:id/url` → `file-upload.ts`
+ *    `signFileEntityUrl`;
+ *  - approve: `rest/proposals.ts` `POST /proposals/:id/approve`.
+ * Fields the SDK does not read stay on the objects (index signatures): the pod
+ * sends more than is typed here. The mock pod (`@synap-core/sdk/testing`)
+ * answers these shapes; `src/__tests__/connect.typed.test.ts` drives both.
+ */
+
+/** One entity, as `GET /entities` and `GET /entities/:id` answer it (`WireEntitySchema`). */
+export interface PodEntity {
+  id: string;
+  profileSlug: string;
+  /** Deprecated alias of `profileSlug`, still sent. */
+  type?: string;
+  title?: string | null;
+  preview?: string | null;
+  description?: string | null;
+  properties: Record<string, unknown>;
+  systemData?: Record<string, unknown>;
+  userId: string;
+  workspaceId?: string | null;
+  documentId?: string | null;
+  version?: number;
+  /** ISO 8601. */
+  createdAt?: string;
+  updatedAt?: string;
+  /** The roles it wears, with `includeFacets`; absent when it wears none. */
+  facetSlugs?: string[];
+  /** Each role's overlay, with `includeFacets`; absent when it wears none. */
+  facets?: PodEntityFacet[];
+  [key: string]: unknown;
+}
+
+/** One role an entity wears (`FacetRowAnnotation`). */
+export interface PodEntityFacet {
+  facetId: string;
+  /** The role, e.g. `lead`. */
+  slug: string;
+  properties: Record<string, unknown>;
+  status: string | null;
+}
+
+export interface ListEntitiesOptions {
+  /** One granted space. Omitted: every space the connection can read. */
+  workspaceId?: string;
+  /** One kind, e.g. `post`. */
+  profileSlug?: string;
+  /** 1-1000 (the pod's bounds); the pod's default is 20. */
+  limit?: number;
+  offset?: number;
+  /** e.g. `updatedAt:desc`. */
+  sort?: string;
+  /** With `workspaceId`: also the person's pod-wide rows (the pod's default: true). */
+  includePodWide?: boolean;
+  /** Only the entities wearing this role, e.g. `lead`. */
+  facetSlug?: string;
+  /** Put `facetSlugs` and `facets` on each row that wears a role. */
+  includeFacets?: boolean;
+}
+
+export type PodConnectionSource = "graph" | "property" | "thread" | "context_channel" | "focus_session";
+
+/** One edge of `GET /entities/:id/connections` (`EntityConnection`). */
+export interface PodEntityConnection {
+  /** The other end: an entity, or the channel / session for those sources. */
+  entityId: string;
+  /** The other entity's row (title, `type` = its kind, workspaceId, facetSlugs, …); null for channels and sessions. */
+  entity: {
+    title?: string | null;
+    type?: string | null;
+    workspaceId?: string | null;
+    facetSlugs?: string[] | null;
+    [key: string]: unknown;
+  } | null;
+  label: string;
+  direction: "outgoing" | "incoming" | "structural";
+  source: PodConnectionSource;
+  relationId?: string;
+  relationType?: string;
+  storedAs?: "link";
+  propertySlug?: string;
+  propertyLabel?: string;
+  channelId?: string;
+  channelRelationshipType?: string;
+  channelTitle?: string | null;
+  channelWorkspaceId?: string | null;
+  focusSessionId?: string;
+  focusSessionGoal?: string;
+  focusSessionStatus?: string;
+  focusSessionWorkspaceId?: string | null;
+  /** ISO 8601, or null (a property link has no date). */
+  createdAt?: string | null;
+  [key: string]: unknown;
+}
+
+export interface PodEntityConnections {
+  connections: PodEntityConnection[];
+  counts: {
+    total: number;
+    graph: number;
+    structural: number;
+    threads: number;
+    contextChannels: number;
+    focusSessions: number;
+  };
+}
+
+export interface GetEntityConnectionsOptions {
+  /** A space lens; omitted = everything the connection can read. */
+  workspaceId?: string;
+  /** Per source, 1-200 (the pod's default: 50). */
+  limit?: number;
+}
+
+/** A document's top-level section (`listDocumentSections`). */
+export interface PodDocumentSection {
+  id: string;
+  /** Who owns it (a person's section is not an agent's to change). */
+  owner: string;
+  title: string | null;
+  author: string | null;
+}
+
+/** `GET /documents/:id` → `document` (`projectAgentDocument`). */
+export interface PodDocument {
+  id: string;
+  title: string;
+  /** `markdown`, `text`, `html`, … */
+  type: string;
+  language: string | null;
+  workspaceId: string | null;
+  format: "raw" | "readable";
+  /** Markdown; `readable` replaces embeds by their fallback text. */
+  content: string;
+  /** Pass back as `baseRevision` on a guarded edit. */
+  revision: number;
+  version: number;
+  sections: PodDocumentSection[];
+  /** What will not render; null when the check could not run (`diagnosticsError`). */
+  diagnostics: unknown[] | null;
+  diagnosticsError?: string;
+  updatedAt: string;
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+export interface GetDocumentOptions {
+  /** `raw` (the stored markdown, the pod's default) or `readable`. */
+  format?: "raw" | "readable";
+}
+
+/** `focus_sessions.status` (`@synap-core/types/focus-sessions` SESSION_STATUSES). */
+export type PodSessionStatus = "active" | "paused" | "forming" | "scheduled" | "closed" | "failed" | "cancelled" | "stale";
+
+/**
+ * One declared deliverable of a session (`expectedOutputWireSchema`). A slot
+ * with `owner: "human"` is waiting on the person: `blockedReason` and `why` say
+ * for what, `ask` how they can answer (confirm, choose, form, act, provide).
+ */
+export interface PodSessionSlot {
+  kind: string;
+  label: string;
+  key?: string;
+  optional?: boolean;
+  status?: "pending" | "done";
+  /** Absent = `agent`. */
+  owner?: "human" | "agent";
+  blockedReason?: string;
+  why?: string;
+  /** ISO 8601, stamped by the pod with `owner: "human"`. */
+  owedSince?: string;
+  /** How the person can answer (`@synap-core/types/ask`), or null. */
+  ask?: unknown;
+  answer?: {
+    text: string;
+    messageId: string | null;
+    answeredBy: string;
+    answeredAt: string;
+    question?: string;
+    value?: unknown;
+    [key: string]: unknown;
+  };
+  retiredAt?: string;
+  [key: string]: unknown;
+}
+
+/** One row of `GET /focus-sessions`. `expectedOutputs` is always an array here (the SDK drops anything else). */
+export interface PodFocusSession {
+  id: string;
+  workspaceId: string | null;
+  projectId: string | null;
+  userId: string;
+  title: string | null;
+  goal: string;
+  status: PodSessionStatus | (string & {});
+  templateId: string | null;
+  expectedOutputs: PodSessionSlot[];
+  channelId: string | null;
+  progress: number | null;
+  currentStage: string | null;
+  agentIds: string[];
+  closedAt: string | null;
+  metadata: unknown;
+  startedAt: string;
+  createdAt: string;
+  updatedAt: string;
+  /** Projected by the list door: `work`, `run` (a playbook or automation ran it) or `receipt`. */
+  kind?: "work" | "run" | "receipt";
+  /** Projected by the list door: an agent-started session the person has not accepted yet. */
+  triage?: { pending: boolean; acceptedAt: string | null; acceptedBy: string | null };
+  [key: string]: unknown;
+}
+
+export interface ListFocusSessionsOptions {
+  /** A space; `workspaceId` or `projectId` is required (the pod's rule). */
+  workspaceId?: string;
+  projectId?: string;
+  /** Default `all` (the pod's default on this door). */
+  status?: PodSessionStatus | "all";
+  /** 1-50 (the pod's bounds); the pod's default is 20. */
+  limit?: number;
+  /** Triage lens: `all` (default here), `default` (hides unaccepted agent sessions), `triage`. */
+  lens?: "all" | "default" | "triage";
+  /** Population lens: `all` (default here), `work`, `run`, `receipt`. */
+  kind?: "all" | "work" | "run" | "receipt";
+  /** Sessions about one thing. */
+  subjectEntityId?: string;
+}
+
+/** `GET /files/:id/url`: a signed GET for a file entity's blob. */
+export interface PodFileUrl {
+  /** Served as an `attachment`, with the stored type. */
+  url: string;
+  /** ISO 8601; the signature's end (about an hour). */
+  expiresAt: string;
+  /** Decide drawability on this, never on the URL; null when unknown. */
+  mimeType: string | null;
+}
+
+/** `POST /proposals/:id/approve`. */
+export interface PodApproval {
+  proposalId: string;
+  /** The row the approval produced or linked, when it names one. */
+  primaryId?: string;
+  linked?: number;
+  /** The proposal after the approval (status, execution result), when the pod could read it back. */
+  proposal: Record<string, unknown> | null;
+}
+
+export interface ApproveProposalOptions {
+  /**
+   * The proposal's space, when known: refused locally unless the connection
+   * holds `proposal.approve` there. Omitted: needs it in some space, and the
+   * pod checks the proposal's own space.
+   */
+  workspaceId?: string;
+}

package/src/connect/index.ts

@@ -1,11 +1,10 @@
 /**
- * `@synap-core/sdk/connect` — pod-app sign-in, SERVER-ONLY (spec 17 §10.1,
- * doc 18 § SDK): an app connects to a person's own pod as an OAuth 2.1 public
+ * `@synap-core/sdk/connect` — pod-app sign-in, SERVER-ONLY: an app connects to a person's own pod as an OAuth 2.1 public
  * client (CIMD client_id, PKCE S256, `iss`-checked answers), keeps the pod
  * token on its server in a sealed HttpOnly cookie, refreshes it in `proxy.ts`,
  * and reads/writes the pod's Hub API with typed results.
  *
- * Framework-free and Web-standard (Request/Response, WebCrypto): Node 18+,
+ * Framework-free and Web-standard (Request/Response, WebCrypto): Node 20+,
  * edge runtimes, workers. Throws when loaded in a browser (./guard.ts).
  *
  * Invariant (pinned by src/__tests__/connect.guard.test.ts): every file of
@@ -15,20 +14,65 @@ import { assertServerRuntime } from "./guard";
 
 assertServerRuntime();
 
+// What an app on createPodAppAuth uses.
 export { createPodAppAuth, buildClientMetadata, isPrefetchOrAsset, DEFAULT_PATHS, REFRESH_WINDOW_MS } from "./auth";
-export type { PodAppAuth, PodAppAuthConfig, PodAppPaths, RefreshOutcome, RefreshStatus } from "./auth";
-export { discoverPod, canonicalPodUrl, acceptLaunch, safeNextPath } from "./discovery";
-export type { DiscoverOptions, LaunchHint } from "./discovery";
-export {
-  cloudConnectAvailable,
-  startCloudConnect,
-  acceptCloudReturn,
-  cloudBaseUrl,
-  CLOUD_TRANSACTION_TTL_MS,
-} from "./cloud";
+export type { PodAppAuth, PodAppAuthConfig, PodAppClientOptions, PodAppPaths, RefreshOptions, RefreshOutcome, RefreshStatus } from "./auth";
+export { acceptLaunch, safeNextPath } from "./discovery";
+export type { LaunchHint } from "./discovery";
+export { cloudConnectAvailable } from "./cloud";
+export type { CloudConnectConfig } from "./cloud";
+export { createPodClient, can, spaces, reviewUrlFor, connectionActsAs, humanSlots } from "./client";
+export type {
+  ListPendingProposalsOptions,
+  PendingProposal,
+  PendingProposals,
+  PodClient,
+  PodClientOptions,
+  PodError,
+  PodErrorCode,
+  PodRefusalReason,
+  PodResult,
+  PodWriteResult,
+  QueryValue,
+} from "./client";
+export type {
+  ApproveProposalOptions,
+  GetDocumentOptions,
+  GetEntityConnectionsOptions,
+  ListEntitiesOptions,
+  ListFocusSessionsOptions,
+  PodApproval,
+  PodConnectionSource,
+  PodDocument,
+  PodDocumentSection,
+  PodEntity,
+  PodEntityConnection,
+  PodEntityConnections,
+  PodEntityFacet,
+  PodFileUrl,
+  PodFocusSession,
+  PodSessionSlot,
+  PodSessionStatus,
+} from "./hub-types";
+export { ConnectError, isConnectError, parseConnectErrorCode, CONNECT_ERROR_CODES } from "./errors";
+export type { ConnectErrorCode } from "./errors";
+export { isBrowserRuntime } from "./guard";
+export type { AppRequest, ClientMetadataDocument, PodActsAs, PodConnection, PodGrant, PodIssuer, PodSpace, PodUser } from "./types";
+export type { ConnectionStore } from "./store";
+export { createSealedCookieStore } from "./store";
+export type { SealedCookieStoreOptions } from "./store";
+export type { AppSecret } from "./seal";
+
+// Building blocks: what createPodAppAuth is made of, for another framework or
+// store. INTERNAL, not the supported surface: an app on createPodAppAuth needs
+// none of them, and no new export is added here. They stay exported only for
+// 1.x semver; 2.0 moves them to their own entry. (ConnectionStore and
+// createSealedCookieStore above are the supported custom-store seam.)
+export { discoverPod, canonicalPodUrl } from "./discovery";
+export type { DiscoverOptions } from "./discovery";
+export { startCloudConnect, acceptCloudReturn, cloudBaseUrl, CLOUD_TRANSACTION_TTL_MS } from "./cloud";
 export type {
   AcceptCloudReturnOptions,
-  CloudConnectConfig,
   CloudReturn,
   CloudTransaction,
   SealedCloudTransaction,
@@ -55,33 +99,8 @@ export type {
   StartConnectOptions,
   StartedConnect,
 } from "./flow";
-export { createPodClient, can, spaces, reviewUrlFor } from "./client";
-export type {
-  ListPendingProposalsOptions,
-  PendingProposal,
-  PendingProposals,
-  PodClient,
-  PodClientOptions,
-  PodError,
-  PodErrorCode,
-  PodResult,
-  PodWriteResult,
-  QueryValue,
-} from "./client";
-export {
-  createSealedCookieStore,
-  cookieNames,
-  applySetCookies,
-  connectionExpiresAt,
-  markerCookie,
-  readMarker,
-  MARKER_TTL_SEC,
-} from "./store";
-export type { ConnectionStore, CookieNames, SealedCookieStoreOptions } from "./store";
+export { cookieNames, applySetCookies, connectionExpiresAt, markerCookie, readMarker, MARKER_TTL_SEC } from "./store";
+export type { CookieNames } from "./store";
 export { seal, unseal, MIN_SECRET_LENGTH } from "./seal";
-export type { AppSecret, Opened, SealPurpose } from "./seal";
+export type { Opened, SealPurpose } from "./seal";
 export { pkceChallenge } from "./encoding";
-export { ConnectError, isConnectError, parseConnectErrorCode, CONNECT_ERROR_CODES } from "./errors";
-export type { ConnectErrorCode } from "./errors";
-export { isBrowserRuntime } from "./guard";
-export type { AppRequest, ClientMetadataDocument, PodConnection, PodGrant, PodIssuer, PodSpace, PodUser } from "./types";

package/src/connect/rules.ts

@@ -0,0 +1,18 @@
+/**
+ * The shape rules several files of this entry (and the mock pod) apply, in
+ * one place, so a hint or a state accepted in one door is accepted in all.
+ */
+
+/** Hosts that count as this machine (WHATWG keeps IPv6 brackets: "[::1]"). */
+export const LOOPBACK_HOSTS: ReadonlySet<string> = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/** A `synap_space_hint`: a space id (uuid, short id), never a path or a query. */
+export const SPACE_HINT_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** The `state` the Synap Cloud pod chooser accepts and echoes; ours is 43 base64url characters. */
+export const CLOUD_STATE_RE = /^[A-Za-z0-9._~-]{16,256}$/;
+
+/** An IP literal host (dotted IPv4 or bracketed IPv6), as WHATWG URL normalises them. */
+export function isIpLiteral(hostname: string): boolean {
+  return hostname.startsWith("[") || /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname);
+}

package/src/connect/store.ts

@@ -79,16 +79,20 @@ function chunkName(name: string, i: number): string {
   return i === 0 ? name : `${name}.${i}`;
 }
 
+/** One space of the sealed grant; the template slug only when the pod named one (cookies written by 1.4 have none). */
+type StoredSpace = [workspaceId: string, workspaceName: string, permissions: string[], templateSlug?: string];
+
 /** The sealed form: the grant grouped per space (it repeats the space otherwise). */
 interface StoredConnection extends Omit<PodConnection, "grant"> {
-  g: Array<[workspaceId: string, workspaceName: string, permissions: string[]]>;
+  g: StoredSpace[];
 }
 
 function pack(c: PodConnection): StoredConnection {
-  const bySpace = new Map<string, [string, string, string[]]>();
+  const bySpace = new Map<string, StoredSpace>();
   for (const g of c.grant) {
-    const row = bySpace.get(g.workspaceId) ?? [g.workspaceId, g.workspaceName, []];
+    const row: StoredSpace = bySpace.get(g.workspaceId) ?? [g.workspaceId, g.workspaceName, []];
     row[2].push(g.permission);
+    if (g.templateSlug && row[3] === undefined) row[3] = g.templateSlug;
     bySpace.set(g.workspaceId, row);
   }
   const { grant: _grant, ...rest } = c;
@@ -98,8 +102,8 @@ function pack(c: PodConnection): StoredConnection {
 function unpack(s: StoredConnection): PodConnection | null {
   if (!s || typeof s.podUrl !== "string" || typeof s.accessToken !== "string" || !Array.isArray(s.g)) return null;
   const { g, ...rest } = s;
-  const grant: PodGrant[] = g.flatMap(([workspaceId, workspaceName, permissions]) =>
-    permissions.map((permission) => ({ permission, workspaceId, workspaceName })),
+  const grant: PodGrant[] = g.flatMap(([workspaceId, workspaceName, permissions, templateSlug]) =>
+    permissions.map((permission) => ({ permission, workspaceId, workspaceName, ...(typeof templateSlug === "string" ? { templateSlug } : {}) })),
   );
   return { ...rest, grant };
 }

package/src/connect/types.ts

@@ -3,9 +3,9 @@
  *
  * DRIFT RISK: hand-written from the pod's OAuth AS (synap-backend
  * `routers/oauth/routes.ts` /token for a CIMD client, `protocol.ts`
- * `buildAuthorizationServerMetadata`, spec 17 §6.6). The contract fixture
- * `src/__tests__/connect.contract.test.ts` copies the token response; when the
- * backend changes, update both.
+ * `buildAuthorizationServerMetadata`). The contract test
+ * `src/__tests__/connect.contract.test.ts` holds copies of the pod's token and
+ * metadata answers; when the backend changes them, update both.
  */
 
 /** One permission the app asks for, with the sentence the consent screen shows. */
@@ -21,8 +21,25 @@ export interface PodGrant {
   permission: string;
   workspaceId: string;
   workspaceName: string;
+  /**
+   * The template the space was made from (`synap_grant[].templateSlug`, e.g.
+   * `content-os`), when the pod names one: absent for a space made by hand
+   * and from pods that do not send it.
+   */
+  templateSlug?: string;
 }
 
+/**
+ * Who the connection's token acts as (`synap_acts_as` of the token response):
+ *  - `"person"`: an official Synap app; the token is held by the person who
+ *    consented, so their clicks write as them, directly, approvals included
+ *    (where they granted `proposal.approve`);
+ *  - `"agent"`: every other app; the token is the app's own ask-first agent's,
+ *    its writes become proposals the person reviews, and it can never approve.
+ * A pod that does not say is `"agent"`.
+ */
+export type PodActsAs = "person" | "agent";
+
 export interface PodUser {
   id: string;
   name: string;
@@ -75,6 +92,11 @@ export interface PodConnection {
    * never guess one.
    */
   manageUrl?: string;
+  /**
+   * Who the token acts as, as the latest token response said
+   * (`synap_acts_as`). Absent = `"agent"` (read it with `connectionActsAs`).
+   */
+  actsAs?: PodActsAs;
 }
 
 /** One space of the grant, its permissions together (`spaces(connection)`). */
@@ -83,9 +105,11 @@ export interface PodSpace {
   /** "" when the pod sent no name. */
   workspaceName: string;
   permissions: string[];
+  /** The template the space was made from, when the pod names one (`PodGrant.templateSlug`). */
+  templateSlug?: string;
 }
 
-/** The CIMD document an app serves at its client_id URL (spec 17 §6.1). */
+/** The client metadata document (CIMD) an app serves at its client_id URL. */
 export interface ClientMetadataDocument {
   client_id: string;
   client_name: string;

package/src/public/client.ts

@@ -34,12 +34,24 @@
 
 // ── Wire types (hand-written; see DRIFT RISK) ────────────────────────────────
 
+/**
+ * A published body, in the format the pod serves it (backend
+ * `PublicBodyFormatSchema`): `markdown` is text to parse with
+ * `parseSafeMarkdown`; `html` is a whole HTML document (an estimate, a report)
+ * that a page renders ONLY inside `<iframe sandbox="" srcdoc>`, never in its
+ * own DOM. `null`: nothing pinned, or a body that is not text (pdf, docx).
+ */
+export interface PublicBody {
+  format: "markdown" | "html";
+  content: string;
+}
+
 export interface PublicShare {
   resourceType: "entity";
   /** Present only when the publisher allowlisted `title`. */
   title?: string;
   properties: Record<string, string | number | boolean>;
-  body: { format: "markdown"; content: string } | null;
+  body: PublicBody | null;
   /** Publication day, YYYY-MM-DD. */
   publishedOn: string;
 }
@@ -136,7 +148,7 @@ export interface PublicCollectionPage {
 
 /** One published record, with its pinned body. */
 export interface PublicRecord extends PublicRecordSummary {
-  body: { format: "markdown"; content: string } | null;
+  body: PublicBody | null;
 }
 
 /** The collection door's query bounds (backend `parseCollectionQuery`). */

package/src/public/safe-markdown.ts

@@ -12,6 +12,8 @@
  * Everything else is plain text. Extend here — never by rendering HTML.
  */
 
+import type { PublicBody } from "./client";
+
 export type Inline =
   | { type: "text"; text: string }
   | { type: "strong"; text: string }
@@ -112,3 +114,14 @@ export function parseSafeMarkdown(source: string): Block[] {
   flush();
   return blocks;
 }
+
+/**
+ * A published body as a page renders it: markdown -> safe blocks; html -> the
+ * document for a sandboxed frame, never parsed as markdown (its tags would show
+ * as text). One rule for the share page and the site record page.
+ */
+export function bodyOf(body: PublicBody | null | undefined): { blocks: Block[]; html: string | null } {
+  if (!body) return { blocks: [], html: null };
+  if (body.format === "html") return { blocks: [], html: body.content };
+  return { blocks: parseSafeMarkdown(body.content), html: null };
+}

package/src/public/share-model.ts

@@ -8,7 +8,7 @@
  * is honest (a network blip) — it never says anything about the token.
  */
 import type { PublicReadError, PublicResult, PublicShare } from "./client";
-import { parseSafeMarkdown, type Block } from "./safe-markdown";
+import { bodyOf, type Block } from "./safe-markdown";
 import { formatPublicValue, type FormatOptions } from "./site-model";
 
 export const UNAVAILABLE_TITLE = "This link isn't available";
@@ -20,7 +20,10 @@ export type SharePageModel =
       title: string | null;
       /** Property rows exactly as the publisher allowlisted them. */
       properties: Array<{ key: string; value: string }>;
+      /** A markdown body as safe blocks (`[]` for an html body or none). */
       blocks: Block[];
+      /** An html body: render ONLY as `<iframe sandbox="" srcdoc>`. `null` otherwise. */
+      html: string | null;
       publishedOn: string;
     };
 
@@ -41,7 +44,8 @@ export function toSharePageModel(
       key,
       value: formatPublicValue(value, opts),
     })),
-    blocks: share.body ? parseSafeMarkdown(share.body.content) : [],
+    ...bodyOf(share.body),
     publishedOn: share.publishedOn,
   };
 }
+

package/src/public/site-model.ts

@@ -14,7 +14,7 @@ import {
   type PublicRecordSummary,
   type PublicValue,
 } from "./client";
-import { parseSafeMarkdown, type Block } from "./safe-markdown";
+import { bodyOf, type Block } from "./safe-markdown";
 
 export interface FormatOptions {
   /** BCP 47 locale (default `en`). */
@@ -197,8 +197,10 @@ export interface RecordViewModel {
   slug: string | null;
   /** Rows exactly as the publisher allowlisted them, formatted. */
   properties: Array<{ key: string; value: string }>;
-  /** The body as safe blocks (never HTML). */
+  /** A markdown body as safe blocks (`[]` for an html body or none). */
   blocks: Block[];
+  /** An html body: render ONLY as `<iframe sandbox="" srcdoc>`. `null` otherwise. */
+  html: string | null;
   publishedOn: string;
 }
 
@@ -211,7 +213,7 @@ export function toRecordViewModel(record: PublicRecord, opts: FormatOptions = {}
       key,
       value: formatPublicValue(value, opts),
     })),
-    blocks: record.body ? parseSafeMarkdown(record.body.content) : [],
+    ...bodyOf(record.body),
     publishedOn: record.publishedOn,
   };
 }