@synap-core/sdk 1.3.0 → 1.5.0

package/dist/testing.d.cts

@@ -1,5 +1,5 @@
-import { P as PublicForm, a as PublicShare, b as PublicRecord } from './client-CVUT1Mcf.cjs';
-import { P as PodGrant, a as PodUser } from './types-DpqPNaaa.cjs';
+import { P as PublicForm, h as PublicShare, f as PublicRecord } from './client-B50KC2aJ.cjs';
+import { P as PodGrant, a as PodUser, b as PodActsAs, C as ClientMetadataDocument } from './types-DZYNBCq7.cjs';
 
 /**
  * Demo data for the mock pod. Shapes are the `@synap-core/sdk/public` wire
@@ -8,6 +8,12 @@ import { P as PodGrant, a as PodUser } from './types-DpqPNaaa.cjs';
 
 declare const MOCK_FORM: PublicForm;
 declare const MOCK_SHARE: PublicShare;
+/**
+ * A published HTML document (an estimate), as the pod serves an `html` body: a
+ * page renders it only inside `<iframe sandbox="" srcdoc>`, so the script below
+ * never runs.
+ */
+declare const MOCK_HTML_SHARE: PublicShare;
 /** One collection of a mock site: its door config and its live records. */
 interface MockCollection {
     /** Default sort keys (`-` = descending); also the sort keys the door accepts. */
@@ -29,6 +35,90 @@ interface MockSite {
  */
 declare const MOCK_SITE: MockSite;
 
+/**
+ * The mock pod's data as ONE JSON-serialisable shape, so an app's mock mode,
+ * smoke and screenshots replay a recorded snapshot (one file) instead of
+ * fixtures built in app code:
+ *
+ *   import { readFileSync } from "node:fs";
+ *   const seed = parseMockPodSeed(readFileSync("mock/pod-seed.json", "utf8"));
+ *   const pod = createMockAuthServer({ seed });
+ *
+ * Rows are the pod's wire shapes (see `@synap-core/sdk/connect` hub-types):
+ * `entities` as `GET /entities` answers them, `sessions` as `GET
+ * /focus-sessions` rows (missing columns get the pod's defaults), `documents`
+ * as `GET /documents/:id` (`sections` and `diagnostics` answered empty),
+ * `relations` as graph edges for `GET /entities/:id/connections`, `proposals`
+ * as `GET /proposals?view=basic` rows, `spaces` name each granted space's
+ * template (`synap_grant[].templateSlug` on the token response).
+ */
+
+interface MockSeedEntity {
+    id: string;
+    profileSlug?: string;
+    workspaceId?: string | null;
+    title?: string | null;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface MockSeedSession {
+    id: string;
+    workspaceId?: string | null;
+    projectId?: string | null;
+    goal?: string;
+    status?: string;
+    /** Slots; `owner: "human"` ones are what waits on the person. */
+    expectedOutputs?: Array<Record<string, unknown>>;
+    /** The entity it is about: listed among that entity's connections. */
+    subjectEntityId?: string | null;
+    /** ISO 8601; the list is newest first by it. */
+    startedAt?: string;
+    [key: string]: unknown;
+}
+interface MockSeedDocument {
+    id: string;
+    title: string;
+    content: string;
+    type?: string;
+    language?: string | null;
+    workspaceId?: string | null;
+    revision?: number;
+    version?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface MockSeedRelation {
+    id: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    type: string;
+    createdAt?: string;
+}
+interface MockSeedSpace {
+    id: string;
+    name: string;
+    /** The template it came from (e.g. `content-os`); absent = made by hand. */
+    templateSlug?: string;
+}
+interface MockPodSeed {
+    entities?: MockSeedEntity[];
+    sessions?: MockSeedSession[];
+    documents?: MockSeedDocument[];
+    relations?: MockSeedRelation[];
+    /** Missing fields default to a pending `create` of an `entity`, with null ids and the seed's load time. */
+    proposals?: Array<Partial<MockProposal> & {
+        id: string;
+    }>;
+    spaces?: MockSeedSpace[];
+}
+/**
+ * Read a seed (JSON text or an already-parsed value) and check its shape:
+ * every collection optional, each an array of objects carrying its required
+ * string fields; unknown top-level keys are refused (a typo would otherwise
+ * seed nothing). Throws `TypeError` naming the first bad path.
+ */
+declare function parseMockPodSeed(input: string | unknown): MockPodSeed;
+
 /** A placeholder pod origin; never contacted. */
 declare const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
 declare const MOCK_GRANT: PodGrant[];
@@ -36,7 +126,7 @@ declare const MOCK_USER: PodUser;
 type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" | "unreachable" | "server" | "unavailable";
 interface MockAuthServerOptions {
     issuer?: string;
-    /** Issue rotating refresh tokens (PB3). Default true; false = a pod before PB3. */
+    /** Issue rotating refresh tokens. Default true; false = a pod without refresh tokens. */
     refresh?: boolean;
     /** Default 3600 (the pod's 1 h). */
     accessTtlSec?: number;
@@ -44,12 +134,38 @@ interface MockAuthServerOptions {
     refreshIdleSec?: number;
     /** Send `refresh_token_expires_in` with each refresh token. Default false (the pod does not say). */
     advertiseRefreshExpiry?: boolean;
+    /** The reuse grace, seconds. Default 30 (the pod's); 0 = off (a pod without the grace). */
+    refreshGraceSec?: number;
+    /**
+     * `synap_app` on token responses: the connection's id and its page on the
+     * pod console. Default `MOCK_APP`; null = a pod that does not send it.
+     */
+    app?: {
+        id: string;
+        manageUrl: string | null;
+    } | null;
+    /** Entities `GET /entities` answers (with `workspaceId` / `profileSlug` filters). */
+    entities?: Array<Record<string, unknown>>;
     grant?: PodGrant[];
     user?: PodUser;
     /** Override or remove (undefined) metadata fields: a pod too old, a lying issuer. */
     metadata?: Record<string, unknown>;
-    /** Hub writes: "proposed" (ask-first, the default for an app) or "applied". */
+    /**
+     * Hub writes: "proposed" (ask-first, the default for an agent token) or
+     * "applied" (the default for `actsAs: "person"`).
+     */
     writeMode?: "proposed" | "applied";
+    /**
+     * `synap_acts_as` on token responses. Omitted = not sent (a pod that does
+     * not name it; the SDK reads an agent connection).
+     */
+    actsAs?: PodActsAs;
+    /**
+     * The pod's data as one JSON shape (`parseMockPodSeed`). `seed.entities` come
+     * before `entities`; `seed.spaces` put a `templateSlug` on the grant rows of
+     * those spaces.
+     */
+    seed?: MockPodSeed;
     /** Hub paths (after /api/hub) that answer one failure. */
     failures?: Record<string, MockHubFailure>;
     now?: () => number;
@@ -70,6 +186,27 @@ interface AuthorizeDecision {
     /** Override `state` on the answer: a forged answer. */
     state?: string;
 }
+/** A proposal a governed write filed (`GET /proposals` lists the pending ones). */
+interface MockProposal {
+    id: string;
+    proposalType: string;
+    targetType: string;
+    targetId: string | null;
+    status: "pending" | "approved" | "rejected";
+    workspaceId: string | null;
+    createdAt: string;
+    correlationId: string | null;
+    sessionId: string | null;
+    agentUserId: string | null;
+    summary?: string;
+}
+/** The connection's `synap_app` the mock pod answers by default (backend `appTokenResponse`). */
+declare const MOCK_APP: {
+    id: string;
+    manageUrl: string;
+};
+/** The app's agent on the mock pod: who files its proposals. */
+declare const MOCK_APP_AGENT_ID = "agent_mock_app";
 interface MockAuthServer {
     issuer: string;
     fetch: typeof fetch;
@@ -80,6 +217,20 @@ interface MockAuthServer {
         path: string;
         body: unknown;
     }>;
+    /** Proposals: the seeded ones, then those filed by proposed writes, in order. */
+    proposals: MockProposal[];
+    /** Proposals approved through `POST /proposals/:id/approve`, in order. */
+    approvals: string[];
+    /** The person approved or rejected one: it leaves the pending list. */
+    settleProposal(id: string, status: "approved" | "rejected"): void;
+    /** Another instance of the app rotated `token` (its own refresh): returns the pair the pod answered it. */
+    redeemElsewhere(token: string): Promise<{
+        access_token: string;
+        refresh_token: string;
+        expires_in: number;
+    }>;
+    /** Refresh redeems answered within the reuse grace (the same pair again). */
+    graceAnswers: number;
     /** Stand-in for the consent screen: validates the request like /authorize, returns where the pod redirects. */
     authorize(authorizeUrl: string, decision?: AuthorizeDecision): string;
     /** Mark a refresh token used elsewhere: presenting it now is a REUSE (family + live key revoked). */
@@ -90,12 +241,43 @@ interface MockAuthServer {
     reuses: number;
     /** The person revoked the app: every token stops working. */
     revokeAll(): void;
+    /**
+     * The live access keys stop working, the refresh tokens do not: what a
+     * narrow (the slot's key is revoked at once) or a pod-side "Revoke key"
+     * does. The next refresh mints a new key.
+     */
+    revokeAccessKeys(): void;
     /** Live (unrevoked) refresh tokens. */
     liveRefreshTokens(): string[];
     reset(): void;
 }
 declare function createMockAuthServer(options?: MockAuthServerOptions): MockAuthServer;
 
+/** A placeholder Control Plane origin; never contacted. */
+declare const MOCK_CLOUD_URL = "https://cp.mock-synap.test";
+interface MockCloud {
+    url: string;
+    /** The chooser URLs the app sent browsers to. */
+    requests: string[];
+    /**
+     * The person picks `pod` on the chooser: validates the request like the CP,
+     * returns where the CP redirects the browser. Throws on a request the CP
+     * refuses (shown as a page there, never redirected).
+     */
+    choose(location: string, opts: {
+        pod: string;
+        metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri">;
+    }): string;
+    /** The person cancels on the chooser: `<initiate_login_uri>?state=…&error=access_denied`, no `iss`. */
+    cancel(location: string, opts: {
+        metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri">;
+    }): string;
+}
+declare function createMockCloud(options?: {
+    url?: string;
+    allowInsecureLoopback?: boolean;
+}): MockCloud;
+
 /**
  * @synap-core/sdk/testing — a mock pod: a fake `fetch` that answers the pod's
  * public doors (forms, shares, sites) from fixtures, with no network. Inject
@@ -110,12 +292,12 @@ declare function createMockAuthServer(options?: MockAuthServerOptions): MockAuth
  * `credentials: "include"` request is refused (it rejects, as a CORS failure
  * does); with `{ browser: true }` a non-safelisted request header is too.
  *
- *   tokens MOCK_TOKENS.form / .share / .site   the demo form, share and site
+ *   tokens MOCK_TOKENS.form / .share / .htmlShare / .site   the demo form, shares (markdown, html) and site
  *   tokens MOCK_FAILURE_TOKENS.*                one failure on every door
  *   anything else                               the uniform 404
  *
  * Pod-app sign-in (`@synap-core/sdk/connect`): `createMockAuthServer()`, see
- * ./auth-server.ts.
+ * ./auth-server.ts, seeded from one JSON shape (`parseMockPodSeed`, ./seed.ts); Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
  */
 
 /** A placeholder origin; never contacted. */
@@ -123,6 +305,7 @@ declare const MOCK_POD_URL = "https://mock.synap.invalid";
 declare const MOCK_TOKENS: {
     readonly form: "demo-form";
     readonly share: "demo";
+    readonly htmlShare: "demo-html";
     readonly site: "demo-site";
 };
 /** The `Retry-After` the `rateLimitedRetryAfter` token sends. */
@@ -178,4 +361,4 @@ interface MockPod {
 }
 declare function createMockPod(options?: MockPodOptions): MockPod;
 
-export { type AuthorizeDecision, MOCK_AUTH_ISSUER, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockRequest, type MockSite, type MockSubmission, createMockAuthServer, createMockPod };
+export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
-import { P as PublicForm, a as PublicShare, b as PublicRecord } from './client-CVUT1Mcf.js';
-import { P as PodGrant, a as PodUser } from './types-DpqPNaaa.js';
+import { P as PublicForm, h as PublicShare, f as PublicRecord } from './client-B50KC2aJ.js';
+import { P as PodGrant, a as PodUser, b as PodActsAs, C as ClientMetadataDocument } from './types-DZYNBCq7.js';
 
 /**
  * Demo data for the mock pod. Shapes are the `@synap-core/sdk/public` wire
@@ -8,6 +8,12 @@ import { P as PodGrant, a as PodUser } from './types-DpqPNaaa.js';
 
 declare const MOCK_FORM: PublicForm;
 declare const MOCK_SHARE: PublicShare;
+/**
+ * A published HTML document (an estimate), as the pod serves an `html` body: a
+ * page renders it only inside `<iframe sandbox="" srcdoc>`, so the script below
+ * never runs.
+ */
+declare const MOCK_HTML_SHARE: PublicShare;
 /** One collection of a mock site: its door config and its live records. */
 interface MockCollection {
     /** Default sort keys (`-` = descending); also the sort keys the door accepts. */
@@ -29,6 +35,90 @@ interface MockSite {
  */
 declare const MOCK_SITE: MockSite;
 
+/**
+ * The mock pod's data as ONE JSON-serialisable shape, so an app's mock mode,
+ * smoke and screenshots replay a recorded snapshot (one file) instead of
+ * fixtures built in app code:
+ *
+ *   import { readFileSync } from "node:fs";
+ *   const seed = parseMockPodSeed(readFileSync("mock/pod-seed.json", "utf8"));
+ *   const pod = createMockAuthServer({ seed });
+ *
+ * Rows are the pod's wire shapes (see `@synap-core/sdk/connect` hub-types):
+ * `entities` as `GET /entities` answers them, `sessions` as `GET
+ * /focus-sessions` rows (missing columns get the pod's defaults), `documents`
+ * as `GET /documents/:id` (`sections` and `diagnostics` answered empty),
+ * `relations` as graph edges for `GET /entities/:id/connections`, `proposals`
+ * as `GET /proposals?view=basic` rows, `spaces` name each granted space's
+ * template (`synap_grant[].templateSlug` on the token response).
+ */
+
+interface MockSeedEntity {
+    id: string;
+    profileSlug?: string;
+    workspaceId?: string | null;
+    title?: string | null;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface MockSeedSession {
+    id: string;
+    workspaceId?: string | null;
+    projectId?: string | null;
+    goal?: string;
+    status?: string;
+    /** Slots; `owner: "human"` ones are what waits on the person. */
+    expectedOutputs?: Array<Record<string, unknown>>;
+    /** The entity it is about: listed among that entity's connections. */
+    subjectEntityId?: string | null;
+    /** ISO 8601; the list is newest first by it. */
+    startedAt?: string;
+    [key: string]: unknown;
+}
+interface MockSeedDocument {
+    id: string;
+    title: string;
+    content: string;
+    type?: string;
+    language?: string | null;
+    workspaceId?: string | null;
+    revision?: number;
+    version?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface MockSeedRelation {
+    id: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    type: string;
+    createdAt?: string;
+}
+interface MockSeedSpace {
+    id: string;
+    name: string;
+    /** The template it came from (e.g. `content-os`); absent = made by hand. */
+    templateSlug?: string;
+}
+interface MockPodSeed {
+    entities?: MockSeedEntity[];
+    sessions?: MockSeedSession[];
+    documents?: MockSeedDocument[];
+    relations?: MockSeedRelation[];
+    /** Missing fields default to a pending `create` of an `entity`, with null ids and the seed's load time. */
+    proposals?: Array<Partial<MockProposal> & {
+        id: string;
+    }>;
+    spaces?: MockSeedSpace[];
+}
+/**
+ * Read a seed (JSON text or an already-parsed value) and check its shape:
+ * every collection optional, each an array of objects carrying its required
+ * string fields; unknown top-level keys are refused (a typo would otherwise
+ * seed nothing). Throws `TypeError` naming the first bad path.
+ */
+declare function parseMockPodSeed(input: string | unknown): MockPodSeed;
+
 /** A placeholder pod origin; never contacted. */
 declare const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
 declare const MOCK_GRANT: PodGrant[];
@@ -36,7 +126,7 @@ declare const MOCK_USER: PodUser;
 type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" | "unreachable" | "server" | "unavailable";
 interface MockAuthServerOptions {
     issuer?: string;
-    /** Issue rotating refresh tokens (PB3). Default true; false = a pod before PB3. */
+    /** Issue rotating refresh tokens. Default true; false = a pod without refresh tokens. */
     refresh?: boolean;
     /** Default 3600 (the pod's 1 h). */
     accessTtlSec?: number;
@@ -44,12 +134,38 @@ interface MockAuthServerOptions {
     refreshIdleSec?: number;
     /** Send `refresh_token_expires_in` with each refresh token. Default false (the pod does not say). */
     advertiseRefreshExpiry?: boolean;
+    /** The reuse grace, seconds. Default 30 (the pod's); 0 = off (a pod without the grace). */
+    refreshGraceSec?: number;
+    /**
+     * `synap_app` on token responses: the connection's id and its page on the
+     * pod console. Default `MOCK_APP`; null = a pod that does not send it.
+     */
+    app?: {
+        id: string;
+        manageUrl: string | null;
+    } | null;
+    /** Entities `GET /entities` answers (with `workspaceId` / `profileSlug` filters). */
+    entities?: Array<Record<string, unknown>>;
     grant?: PodGrant[];
     user?: PodUser;
     /** Override or remove (undefined) metadata fields: a pod too old, a lying issuer. */
     metadata?: Record<string, unknown>;
-    /** Hub writes: "proposed" (ask-first, the default for an app) or "applied". */
+    /**
+     * Hub writes: "proposed" (ask-first, the default for an agent token) or
+     * "applied" (the default for `actsAs: "person"`).
+     */
     writeMode?: "proposed" | "applied";
+    /**
+     * `synap_acts_as` on token responses. Omitted = not sent (a pod that does
+     * not name it; the SDK reads an agent connection).
+     */
+    actsAs?: PodActsAs;
+    /**
+     * The pod's data as one JSON shape (`parseMockPodSeed`). `seed.entities` come
+     * before `entities`; `seed.spaces` put a `templateSlug` on the grant rows of
+     * those spaces.
+     */
+    seed?: MockPodSeed;
     /** Hub paths (after /api/hub) that answer one failure. */
     failures?: Record<string, MockHubFailure>;
     now?: () => number;
@@ -70,6 +186,27 @@ interface AuthorizeDecision {
     /** Override `state` on the answer: a forged answer. */
     state?: string;
 }
+/** A proposal a governed write filed (`GET /proposals` lists the pending ones). */
+interface MockProposal {
+    id: string;
+    proposalType: string;
+    targetType: string;
+    targetId: string | null;
+    status: "pending" | "approved" | "rejected";
+    workspaceId: string | null;
+    createdAt: string;
+    correlationId: string | null;
+    sessionId: string | null;
+    agentUserId: string | null;
+    summary?: string;
+}
+/** The connection's `synap_app` the mock pod answers by default (backend `appTokenResponse`). */
+declare const MOCK_APP: {
+    id: string;
+    manageUrl: string;
+};
+/** The app's agent on the mock pod: who files its proposals. */
+declare const MOCK_APP_AGENT_ID = "agent_mock_app";
 interface MockAuthServer {
     issuer: string;
     fetch: typeof fetch;
@@ -80,6 +217,20 @@ interface MockAuthServer {
         path: string;
         body: unknown;
     }>;
+    /** Proposals: the seeded ones, then those filed by proposed writes, in order. */
+    proposals: MockProposal[];
+    /** Proposals approved through `POST /proposals/:id/approve`, in order. */
+    approvals: string[];
+    /** The person approved or rejected one: it leaves the pending list. */
+    settleProposal(id: string, status: "approved" | "rejected"): void;
+    /** Another instance of the app rotated `token` (its own refresh): returns the pair the pod answered it. */
+    redeemElsewhere(token: string): Promise<{
+        access_token: string;
+        refresh_token: string;
+        expires_in: number;
+    }>;
+    /** Refresh redeems answered within the reuse grace (the same pair again). */
+    graceAnswers: number;
     /** Stand-in for the consent screen: validates the request like /authorize, returns where the pod redirects. */
     authorize(authorizeUrl: string, decision?: AuthorizeDecision): string;
     /** Mark a refresh token used elsewhere: presenting it now is a REUSE (family + live key revoked). */
@@ -90,12 +241,43 @@ interface MockAuthServer {
     reuses: number;
     /** The person revoked the app: every token stops working. */
     revokeAll(): void;
+    /**
+     * The live access keys stop working, the refresh tokens do not: what a
+     * narrow (the slot's key is revoked at once) or a pod-side "Revoke key"
+     * does. The next refresh mints a new key.
+     */
+    revokeAccessKeys(): void;
     /** Live (unrevoked) refresh tokens. */
     liveRefreshTokens(): string[];
     reset(): void;
 }
 declare function createMockAuthServer(options?: MockAuthServerOptions): MockAuthServer;
 
+/** A placeholder Control Plane origin; never contacted. */
+declare const MOCK_CLOUD_URL = "https://cp.mock-synap.test";
+interface MockCloud {
+    url: string;
+    /** The chooser URLs the app sent browsers to. */
+    requests: string[];
+    /**
+     * The person picks `pod` on the chooser: validates the request like the CP,
+     * returns where the CP redirects the browser. Throws on a request the CP
+     * refuses (shown as a page there, never redirected).
+     */
+    choose(location: string, opts: {
+        pod: string;
+        metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri">;
+    }): string;
+    /** The person cancels on the chooser: `<initiate_login_uri>?state=…&error=access_denied`, no `iss`. */
+    cancel(location: string, opts: {
+        metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri">;
+    }): string;
+}
+declare function createMockCloud(options?: {
+    url?: string;
+    allowInsecureLoopback?: boolean;
+}): MockCloud;
+
 /**
  * @synap-core/sdk/testing — a mock pod: a fake `fetch` that answers the pod's
  * public doors (forms, shares, sites) from fixtures, with no network. Inject
@@ -110,12 +292,12 @@ declare function createMockAuthServer(options?: MockAuthServerOptions): MockAuth
  * `credentials: "include"` request is refused (it rejects, as a CORS failure
  * does); with `{ browser: true }` a non-safelisted request header is too.
  *
- *   tokens MOCK_TOKENS.form / .share / .site   the demo form, share and site
+ *   tokens MOCK_TOKENS.form / .share / .htmlShare / .site   the demo form, shares (markdown, html) and site
  *   tokens MOCK_FAILURE_TOKENS.*                one failure on every door
  *   anything else                               the uniform 404
  *
  * Pod-app sign-in (`@synap-core/sdk/connect`): `createMockAuthServer()`, see
- * ./auth-server.ts.
+ * ./auth-server.ts, seeded from one JSON shape (`parseMockPodSeed`, ./seed.ts); Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
  */
 
 /** A placeholder origin; never contacted. */
@@ -123,6 +305,7 @@ declare const MOCK_POD_URL = "https://mock.synap.invalid";
 declare const MOCK_TOKENS: {
     readonly form: "demo-form";
     readonly share: "demo";
+    readonly htmlShare: "demo-html";
     readonly site: "demo-site";
 };
 /** The `Retry-After` the `rateLimitedRetryAfter` token sends. */
@@ -178,4 +361,4 @@ interface MockPod {
 }
 declare function createMockPod(options?: MockPodOptions): MockPod;
 
-export { type AuthorizeDecision, MOCK_AUTH_ISSUER, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockRequest, type MockSite, type MockSubmission, createMockAuthServer, createMockPod };
+export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };