@decocms/blocks 8.5.2 → 8.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/dist/async/default.d.ts +10 -0
  2. package/dist/async/default.d.ts.map +1 -0
  3. package/dist/async/default.js +5 -0
  4. package/dist/async/default.js.map +1 -0
  5. package/dist/async/node.d.ts +3 -0
  6. package/dist/async/node.d.ts.map +1 -0
  7. package/dist/async/node.js +11 -0
  8. package/dist/async/node.js.map +1 -0
  9. package/dist/async/types.d.ts +6 -0
  10. package/dist/async/types.d.ts.map +1 -0
  11. package/dist/async/types.js +2 -0
  12. package/dist/async/types.js.map +1 -0
  13. package/dist/index.d.ts +1 -1
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +1 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/v8/bucketing.d.ts +24 -0
  18. package/dist/v8/bucketing.d.ts.map +1 -0
  19. package/dist/v8/bucketing.js +78 -0
  20. package/dist/v8/bucketing.js.map +1 -0
  21. package/dist/v8/builtins/campaigns.d.ts +36 -0
  22. package/dist/v8/builtins/campaigns.d.ts.map +1 -0
  23. package/dist/v8/builtins/campaigns.js +107 -0
  24. package/dist/v8/builtins/campaigns.js.map +1 -0
  25. package/dist/v8/builtins/data.d.ts +2 -2
  26. package/dist/v8/builtins/data.js +2 -2
  27. package/dist/v8/builtins/experiments.d.ts +27 -0
  28. package/dist/v8/builtins/experiments.d.ts.map +1 -0
  29. package/dist/v8/builtins/experiments.js +62 -0
  30. package/dist/v8/builtins/experiments.js.map +1 -0
  31. package/dist/v8/builtins/index.d.ts.map +1 -1
  32. package/dist/v8/builtins/index.js +7 -2
  33. package/dist/v8/builtins/index.js.map +1 -1
  34. package/dist/v8/builtins/matchers.d.ts +0 -14
  35. package/dist/v8/builtins/matchers.d.ts.map +1 -1
  36. package/dist/v8/builtins/matchers.js +0 -19
  37. package/dist/v8/builtins/matchers.js.map +1 -1
  38. package/dist/v8/cli/builtins.d.ts +6 -0
  39. package/dist/v8/cli/builtins.d.ts.map +1 -1
  40. package/dist/v8/cli/builtins.js +19 -0
  41. package/dist/v8/cli/builtins.js.map +1 -1
  42. package/dist/v8/cli/check/index.d.ts.map +1 -1
  43. package/dist/v8/cli/check/index.js +231 -8
  44. package/dist/v8/cli/check/index.js.map +1 -1
  45. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  46. package/dist/v8/cli/schema/builtinSchemas.js +76 -21
  47. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  48. package/dist/v8/cli/schema/generate.d.ts.map +1 -1
  49. package/dist/v8/cli/schema/generate.js +48 -2
  50. package/dist/v8/cli/schema/generate.js.map +1 -1
  51. package/dist/v8/client.d.ts +25 -0
  52. package/dist/v8/client.d.ts.map +1 -1
  53. package/dist/v8/client.js +58 -10
  54. package/dist/v8/client.js.map +1 -1
  55. package/dist/v8/cms.d.ts.map +1 -1
  56. package/dist/v8/cms.js +93 -42
  57. package/dist/v8/cms.js.map +1 -1
  58. package/dist/v8/content.d.ts +45 -0
  59. package/dist/v8/content.d.ts.map +1 -1
  60. package/dist/v8/content.js +68 -2
  61. package/dist/v8/content.js.map +1 -1
  62. package/dist/v8/current.d.ts +28 -0
  63. package/dist/v8/current.d.ts.map +1 -0
  64. package/dist/v8/current.js +77 -0
  65. package/dist/v8/current.js.map +1 -0
  66. package/dist/v8/draft.d.ts +40 -21
  67. package/dist/v8/draft.d.ts.map +1 -1
  68. package/dist/v8/draft.js +160 -25
  69. package/dist/v8/draft.js.map +1 -1
  70. package/dist/v8/experiments.d.ts +107 -0
  71. package/dist/v8/experiments.d.ts.map +1 -0
  72. package/dist/v8/experiments.js +292 -0
  73. package/dist/v8/experiments.js.map +1 -0
  74. package/dist/v8/hosts.d.ts +3 -2
  75. package/dist/v8/hosts.d.ts.map +1 -1
  76. package/dist/v8/hosts.js +3 -2
  77. package/dist/v8/hosts.js.map +1 -1
  78. package/dist/v8/index.d.ts +7 -5
  79. package/dist/v8/index.d.ts.map +1 -1
  80. package/dist/v8/index.js +6 -4
  81. package/dist/v8/index.js.map +1 -1
  82. package/dist/v8/remoteLoader.d.ts.map +1 -1
  83. package/dist/v8/remoteLoader.js +166 -20
  84. package/dist/v8/remoteLoader.js.map +1 -1
  85. package/dist/v8/resolver.d.ts +4 -2
  86. package/dist/v8/resolver.d.ts.map +1 -1
  87. package/dist/v8/resolver.js +11 -3
  88. package/dist/v8/resolver.js.map +1 -1
  89. package/dist/v8/settings.d.ts +16 -4
  90. package/dist/v8/settings.d.ts.map +1 -1
  91. package/dist/v8/settings.js +24 -21
  92. package/dist/v8/settings.js.map +1 -1
  93. package/dist/v8/types.d.ts +126 -21
  94. package/dist/v8/types.d.ts.map +1 -1
  95. package/package.json +35 -1
  96. package/src/async/default.ts +13 -0
  97. package/src/async/node.ts +12 -0
  98. package/src/async/types.ts +5 -0
  99. package/src/index.ts +4 -0
  100. package/src/v8/bucketing.ts +88 -0
  101. package/src/v8/builtins/campaigns.ts +120 -0
  102. package/src/v8/builtins/data.ts +2 -2
  103. package/src/v8/builtins/experiments.ts +72 -0
  104. package/src/v8/builtins/index.ts +7 -2
  105. package/src/v8/builtins/matchers.ts +0 -26
  106. package/src/v8/cli/builtins.ts +23 -0
  107. package/src/v8/cli/check/index.ts +289 -8
  108. package/src/v8/cli/schema/builtinSchemas.ts +82 -22
  109. package/src/v8/cli/schema/generate.ts +48 -3
  110. package/src/v8/client.ts +76 -10
  111. package/src/v8/cms.ts +108 -43
  112. package/src/v8/content.ts +86 -2
  113. package/src/v8/current.ts +98 -0
  114. package/src/v8/draft.ts +170 -30
  115. package/src/v8/experiments.ts +340 -0
  116. package/src/v8/hosts.ts +3 -2
  117. package/src/v8/index.ts +8 -4
  118. package/src/v8/remoteLoader.ts +190 -25
  119. package/src/v8/resolver.ts +14 -4
  120. package/src/v8/settings.ts +35 -29
  121. package/src/v8/types.ts +128 -19
@@ -103,9 +103,23 @@ interface BlockInfo {
103
103
 
104
104
  const BUILT_IN_TYPES_SOURCE = `
105
105
  export interface Seo { title: string; description: string }
106
+ export interface SeoFields { title?: string; description?: string }
106
107
  export interface Route { name: string; path: string }
108
+ export interface NameStates { [name: string]: boolean }
107
109
  `;
108
110
 
111
+ /**
112
+ * Built-in blocks a field can take, by the interface in BUILT_IN_TYPES_SOURCE
113
+ * their value has: `split-traffic` and `calendar` resolve to name →
114
+ * true/false, so a field typed `Assignments` (or any `Record<string,
115
+ * boolean>`) can hold the saved `experiments` or `campaigns` block. A block
116
+ * map that declares the name replaces it.
117
+ */
118
+ const BUILT_IN_RETURNS: Record<string, string> = {
119
+ "split-traffic": "NameStates",
120
+ calendar: "NameStates",
121
+ };
122
+
109
123
  /** The package version, written into the schema's `version`. */
110
124
 
111
125
  function siteName(root: string): string {
@@ -177,6 +191,7 @@ export async function generateSchema(paths: DecoPaths): Promise<SchemaResult> {
177
191
  });
178
192
  const builtInTypes = project.sourceFile(builtInTypesFile);
179
193
  const seoType = builtInTypes.getInterfaceType("Seo");
194
+ const seoFieldsType = builtInTypes.getInterfaceType("SeoFields");
180
195
  const routeType = builtInTypes.getInterfaceType("Route");
181
196
  const source = project.sourceFile(blockMap);
182
197
  const diagnostics: SchemaDiagnostic[] = [];
@@ -269,8 +284,15 @@ export async function generateSchema(paths: DecoPaths): Promise<SchemaResult> {
269
284
  // -------------------------------------------------------------------------
270
285
  // 2. Fields → blocks: which functions' return types fit an object field.
271
286
  // -------------------------------------------------------------------------
272
- const STRUCTURAL = new Set<string>(["lazy", "multivariate", "secret", "always", "never", "date"]);
273
- const candidates = infos.filter(
287
+ const STRUCTURAL = new Set<string>([
288
+ "lazy",
289
+ "multivariate",
290
+ "secret",
291
+ "always",
292
+ "never",
293
+ "campaign",
294
+ ]);
295
+ const candidates: Pick<BlockInfo, "key" | "returnType">[] = infos.filter(
274
296
  (info) =>
275
297
  info.group !== "sections" &&
276
298
  info.group !== "matchers" &&
@@ -279,6 +301,10 @@ export async function generateSchema(paths: DecoPaths): Promise<SchemaResult> {
279
301
  !info.returnType.isUnknown() &&
280
302
  !nonNullable(info.returnType).isNever(),
281
303
  );
304
+ for (const [key, typeName] of Object.entries(BUILT_IN_RETURNS)) {
305
+ if (infos.some((info) => info.key === key)) continue;
306
+ candidates.push({ key, returnType: builtInTypes.getInterfaceType(typeName) });
307
+ }
282
308
  const fitCache = new Map<unknown, string[]>();
283
309
  const definitions: Record<string, any> = {};
284
310
 
@@ -380,7 +406,12 @@ export async function generateSchema(paths: DecoPaths): Promise<SchemaResult> {
380
406
  };
381
407
  }
382
408
 
383
- const seoRefs = ctx.fitting(seoType).map((key) => ({ $ref: `#/definitions/${key}` }));
409
+ // The page's seo field: blocks that return a Seo, or only optional SEO
410
+ // fields of their own (a migrated site's PageSeo); loaders of content that
411
+ // happens to carry a title stay out.
412
+ const seoRefs = candidates
413
+ .filter((c) => returnFits(c.returnType, seoType) || hasSeoFields(c.returnType, seoFieldsType))
414
+ .map((c) => ({ $ref: `#/definitions/${toBase64(c.key)}` }));
384
415
  for (const name of BUILT_IN_BLOCKS) {
385
416
  if (declared.has(name)) continue;
386
417
  const group = BUILT_IN_GROUPS[name];
@@ -465,6 +496,20 @@ function sameNamedType(a: Type, b: Type): boolean {
465
496
  return sa !== undefined && sa === sb;
466
497
  }
467
498
 
499
+ /**
500
+ * Whether a block returns SEO fields of its own: an object (not a list) whose
501
+ * every property is optional, such as a migrated site's PageSeo, with a
502
+ * `title` or a `description`, each a string when set. A loader whose result
503
+ * has required fields (a blog post's `title` and `excerpt`, a category's
504
+ * `name`) is content, not SEO, and stays out.
505
+ */
506
+ function hasSeoFields(returnType: Type, seoFields: Type): boolean {
507
+ const source = nonNullable(returnType);
508
+ if (source.isArray() || !source.isObject() || !isWeakType(source)) return false;
509
+ if (!source.getProperty("title") && !source.getProperty("description")) return false;
510
+ return source.isAssignableTo(seoFields);
511
+ }
512
+
468
513
  /**
469
514
  * Does a function returning `returnType` fit a field of type `field`? The
470
515
  * TypeScript rule (assignability of the awaited, non-null types), except for
package/src/v8/client.ts CHANGED
@@ -1,8 +1,12 @@
1
1
  /**
2
2
  * A client: one revision, loaded on first use and read for the rest of its
3
- * life, plus a memo of block results. Create one per request.
3
+ * life, plus a memo of block results, and the inputs it was created with
4
+ * (the version, the visitor, the date, the tests and campaigns it was given).
5
+ * Create one per request.
4
6
  */
7
+ import { CAMPAIGN_OVERRIDES, EXPERIMENT_OVERRIDES, type Overrides } from "./current.ts";
5
8
  import { errors, isResolutionError, ResolutionError } from "./errors.ts";
9
+ import type { Visitor } from "./experiments.ts";
6
10
  import { isBlock } from "./json.ts";
7
11
  import { Resolver } from "./resolver.ts";
8
12
  import type { ClientTelemetry } from "./telemetry.ts";
@@ -23,6 +27,16 @@ interface ClientOptions {
23
27
  blocks: Blocks;
24
28
  /** The built-ins, with this CMS's `secret`. */
25
29
  builtIns: Readonly<Blocks>;
30
+ /** Who is visiting (copied and frozen); `null` for none. */
31
+ visitor?: Visitor | null;
32
+ /** The version it was created with: `undefined` for the current release. */
33
+ version?: string;
34
+ /** The date campaigns run at, in ms since the epoch. */
35
+ date: number;
36
+ /** The tests it was given, on or off by name (frozen); `undefined` for none. */
37
+ experiments?: Overrides;
38
+ /** The campaigns it was given, on or off by name (frozen); `undefined` for none. */
39
+ campaigns?: Overrides;
26
40
  onCollision?: (name: string) => void;
27
41
  telemetry?: ClientTelemetry;
28
42
  }
@@ -32,10 +46,36 @@ type Loaded = { resolver: Resolver; snapshot: Snapshot } | { error: CMSError };
32
46
  export class CMSClient implements Client {
33
47
  readonly #options: ClientOptions;
34
48
  readonly #reported = new WeakSet<CMSError>();
49
+ readonly #visitor: Visitor | null;
35
50
  #loaded: Promise<Loaded> | undefined;
51
+ /** The revision loaded, once it is. */
52
+ #revision: string | undefined;
36
53
 
37
54
  constructor(options: ClientOptions) {
38
55
  this.#options = options;
56
+ this.#visitor = copyVisitor(options.visitor);
57
+ }
58
+
59
+ get visitor(): Visitor | null {
60
+ return this.#visitor;
61
+ }
62
+
63
+ get version(): string | undefined {
64
+ return this.#options.version ?? this.#revision;
65
+ }
66
+
67
+ get date(): Date {
68
+ return new Date(this.#options.date);
69
+ }
70
+
71
+ /** Read by the built-in `split-traffic` (see ./current.ts). */
72
+ get [EXPERIMENT_OVERRIDES](): Overrides | undefined {
73
+ return this.#options.experiments;
74
+ }
75
+
76
+ /** Read by the built-in `calendar` (see ./current.ts). */
77
+ get [CAMPAIGN_OVERRIDES](): Overrides | undefined {
78
+ return this.#options.campaigns;
39
79
  }
40
80
 
41
81
  async resolve<T = unknown>(target: unknown, options: ResolveOptions = {}): Promise<Result<T>> {
@@ -102,16 +142,20 @@ export class CMSClient implements Client {
102
142
 
103
143
  #load(): Promise<Loaded> {
104
144
  this.#loaded ??= this.#options.load().then(
105
- (snapshot): Loaded => ({
106
- snapshot,
107
- resolver: new Resolver({
145
+ (snapshot): Loaded => {
146
+ this.#revision = snapshot.revision;
147
+ return {
108
148
  snapshot,
109
- blocks: this.#options.blocks,
110
- builtIns: this.#options.builtIns,
111
- onCollision: this.#options.onCollision,
112
- onBlock: this.#options.telemetry?.block,
113
- }),
114
- }),
149
+ resolver: new Resolver({
150
+ snapshot,
151
+ blocks: this.#options.blocks,
152
+ builtIns: this.#options.builtIns,
153
+ client: this,
154
+ onCollision: this.#options.onCollision,
155
+ onBlock: this.#options.telemetry?.block,
156
+ }),
157
+ };
158
+ },
115
159
  (error): Loaded => ({
116
160
  error: isResolutionError(error)
117
161
  ? error
@@ -131,6 +175,28 @@ export class CMSClient implements Client {
131
175
  }
132
176
  }
133
177
 
178
+ /**
179
+ * The client's own frozen copy of a visitor, so a caller changing its object
180
+ * later changes no client; `null` for anything that isn't one.
181
+ */
182
+ function copyVisitor(visitor: Visitor | null | undefined): Visitor | null {
183
+ if (typeof visitor !== "object" || visitor === null || typeof visitor.id !== "string") {
184
+ return null;
185
+ }
186
+ const strings = (value: unknown): string[] =>
187
+ Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
188
+ const copy: Visitor = {
189
+ id: visitor.id,
190
+ active: Object.freeze(strings(visitor.active)) as string[],
191
+ inactiveDrawn: Object.freeze(strings(visitor.inactiveDrawn)) as string[],
192
+ pct: Object.freeze(Object.assign(Object.create(null), visitor.pct)),
193
+ };
194
+ if (typeof visitor.exp === "object" && visitor.exp !== null) {
195
+ copy.exp = Object.freeze(Object.assign(Object.create(null), visitor.exp));
196
+ }
197
+ return Object.freeze(copy);
198
+ }
199
+
134
200
  /** Plain code-unit order, the same on every server and locale. */
135
201
  function byCodeUnit(a: string, b: string): number {
136
202
  return a < b ? -1 : a > b ? 1 : 0;
package/src/v8/cms.ts CHANGED
@@ -12,17 +12,21 @@ import { builtIns } from "./builtins/index.ts";
12
12
  import { secretBlock } from "./builtins/secret.ts";
13
13
  import { CMSClient } from "./client.ts";
14
14
  import { ContentStore, isLoader, isSnapshot } from "./content.ts";
15
- import { draftCookieFor, endsPreview, parseDraftPointer, readDraftPointer } from "./draft.ts";
15
+ import type { Overrides } from "./current.ts";
16
+ import { draftCookieFor, endsPreview, parseClientVersion, readVersion } from "./draft.ts";
16
17
  import { parseDraftHosts } from "./draftChanges.ts";
17
18
  import { allowsHost, type HostPattern, parseHostPattern } from "./hosts.ts";
18
19
  import { clearGlobals, contentIdentity, fnv1a } from "./identity.ts";
19
20
  import { isPlainObject } from "./json.ts";
20
21
  import { remoteLoader, resetRemoteLoaders } from "./remoteLoader.ts";
21
22
  import {
23
+ deepFreeze,
22
24
  defaultSettings,
23
25
  isStatic,
24
26
  parseCodeHosts,
27
+ previewHosts,
25
28
  readSettings,
29
+ type SavedSettings,
26
30
  type SettingsCaps,
27
31
  } from "./settings.ts";
28
32
  import {
@@ -34,11 +38,13 @@ import {
34
38
  import type {
35
39
  Blocks,
36
40
  Client,
41
+ ClientOptions,
37
42
  CMS,
38
43
  CMSConfig,
39
44
  EffectiveSettings,
40
45
  Loader,
41
46
  RequestLike,
47
+ RequestVersion,
42
48
  Snapshot,
43
49
  } from "./types.ts";
44
50
  import { forceVariants } from "./variants.ts";
@@ -75,13 +81,15 @@ class CMSInstance {
75
81
  readonly #telemetry: TelemetryPipeline | undefined;
76
82
  readonly #caps: SettingsCaps;
77
83
  /** Settings of a `CMS` block with nothing to run, per release snapshot. */
78
- #staticSettings = new WeakMap<Snapshot, EffectiveSettings>();
84
+ #staticSettings = new WeakMap<Snapshot, SavedSettings>();
85
+ /** Code's `preview.hosts`, parsed: added to the release's own preview hosts, or the only list without a site. */
86
+ readonly #codeHosts: readonly HostPattern[] | undefined;
79
87
  /** The release and time telemetry last read its section. */
80
88
  #telemetryRead: { snapshot: Snapshot; at: number } | undefined;
81
89
  /** One handle per block map, so the same config returns the same object. */
82
90
  readonly #handles = new WeakMap<Blocks, CMS>();
83
91
  /**
84
- * When the next check is due. The first is on the first `forRelease()` or `forDraft()`, not
92
+ * When the next check is due. The first is on the first `client()`, not
85
93
  * at construction: Workers read `Date.now()` as 0 at module scope.
86
94
  */
87
95
  #nextCheck: number | undefined;
@@ -91,10 +99,8 @@ class CMSInstance {
91
99
  this.#interval = interval;
92
100
  this.#store = new ContentStore(contentOf(config), parseDraftHosts(config.preview));
93
101
  this.fingerprint = fingerprintOf(config, interval);
94
- this.#caps = {
95
- hosts: parseCodeHosts(config.preview),
96
- limits: telemetryLimits(config.telemetry),
97
- };
102
+ this.#codeHosts = parseCodeHosts(config.preview);
103
+ this.#caps = { limits: telemetryLimits(config.telemetry) };
98
104
  const destination = resolveDestination(config.telemetry, config.site, config.token);
99
105
  if (destination !== null) {
100
106
  this.#telemetry = new TelemetryPipeline(destination);
@@ -106,17 +112,46 @@ class CMSInstance {
106
112
  this.#builtIns = Object.freeze({ ...builtIns, secret });
107
113
  }
108
114
 
109
- forRelease(blocks: Blocks): Client {
115
+ /**
116
+ * A client for one request: the version it reads (the current release, a
117
+ * published release by its commit SHA, or a draft pointer), the visitor it
118
+ * decides tests for and the date it checks campaigns at (default: now),
119
+ * all passed in, with the tests and campaigns it is given on top.
120
+ */
121
+ client(blocks: Blocks, options: ClientOptions = {}): Client {
110
122
  this.#scheduleUpdate();
123
+ const version = typeof options.version === "string" ? options.version : undefined;
124
+ const date = options.date instanceof Date ? options.date.getTime() : Number.NaN;
125
+ const inputs = {
126
+ version,
127
+ visitor: options.visitor ?? null,
128
+ date: Number.isNaN(date) ? Date.now() : date,
129
+ experiments: overridesOf(options.experiments),
130
+ campaigns: overridesOf(options.campaigns),
131
+ };
132
+ if (version === undefined) return this.#client(blocks, this.#release(blocks), inputs);
133
+ const parsed = parseClientVersion(version);
134
+ // A version that doesn't parse fails on the first read, as an invalid pointer always has.
135
+ if (parsed === null) return this.#client(blocks, () => this.#store.draft(version), inputs);
136
+ if (parsed.kind === "revision") {
137
+ return this.#client(blocks, () => this.#store.revision(parsed.sha), inputs);
138
+ }
139
+ const { variants } = parsed.pointer;
140
+ const load = () => this.#store.draft(version);
141
+ if (variants === undefined) return this.#client(blocks, load, inputs);
142
+ return this.#client(blocks, () => load().then((s) => forceVariants(s, variants)), inputs);
143
+ }
144
+
145
+ /** Loads the current release, keeping telemetry on the release's settings. */
146
+ #release(blocks: Blocks): () => Promise<Snapshot> {
111
147
  const telemetry = this.#telemetry;
112
- if (telemetry === undefined) return this.#client(blocks, () => this.#store.release());
113
- return this.#client(blocks, () =>
148
+ if (telemetry === undefined) return () => this.#store.release();
149
+ return () =>
114
150
  this.#store.release().then(async (snapshot) => {
115
151
  telemetry.useRelease(snapshot);
116
152
  await this.#followTelemetrySettings(blocks, telemetry, snapshot);
117
153
  return snapshot;
118
- }),
119
- );
154
+ });
120
155
  }
121
156
 
122
157
  /**
@@ -124,35 +159,26 @@ class CMSInstance {
124
159
  * `CMS` block resolves on each call, so a field with variants is decided
125
160
  * where it's called; one with nothing to run is resolved once per release.
126
161
  */
127
- settings(blocks: Blocks): Promise<EffectiveSettings> {
128
- return this.#settingsOf(blocks, this.#store.current());
162
+ async settings(blocks: Blocks): Promise<EffectiveSettings> {
163
+ const [saved, hosts] = await Promise.all([
164
+ this.#settingsOf(blocks, this.#store.current()),
165
+ this.#store.previewHosts(true),
166
+ ]);
167
+ return deepFreeze({ ...saved, preview: { hosts: previewHosts(hosts, this.#codeHosts) } });
129
168
  }
130
169
 
131
- async draftPointer(blocks: Blocks, request: RequestLike): Promise<string | null> {
132
- const pointer = readDraftPointer(request);
133
- if (pointer === null) return null;
134
- return (await this.#previewAllowed(blocks, request)) ? pointer : null;
170
+ async readVersion(request: RequestLike): Promise<RequestVersion | null> {
171
+ const version = readVersion(request);
172
+ if (version === null) return null;
173
+ return (await this.#previewAllowed(request)) ? version : null;
135
174
  }
136
175
 
137
- async draftCookie(blocks: Blocks, request: RequestLike): Promise<string | null> {
176
+ async draftCookie(request: RequestLike): Promise<string | null> {
138
177
  const cookie = draftCookieFor(request);
139
178
  if (cookie === null) return null;
140
179
  // Ending a preview is allowed anywhere, so a cookie set before a host was removed still goes.
141
180
  if (endsPreview(request)) return cookie;
142
- return (await this.#previewAllowed(blocks, request)) ? cookie : null;
143
- }
144
-
145
- /**
146
- * The draft, with the variants the pointer forces (even for a `local`
147
- * pointer, which names no draft). A draft client is a production client
148
- * reading a draft pointer, so it schedules the release check like any other.
149
- */
150
- forDraft(blocks: Blocks, pointer: string): Client {
151
- this.#scheduleUpdate();
152
- const load = () => this.#store.draft(pointer);
153
- const variants = parseDraftPointer(pointer)?.variants;
154
- if (variants === undefined) return this.#client(blocks, load);
155
- return this.#client(blocks, () => load().then((snapshot) => forceVariants(snapshot, variants)));
181
+ return (await this.#previewAllowed(request)) ? cookie : null;
156
182
  }
157
183
 
158
184
  update(): Promise<{ updated: boolean }> {
@@ -181,7 +207,7 @@ class CMSInstance {
181
207
  this.#telemetryRead = undefined;
182
208
  }
183
209
 
184
- async #settingsOf(blocks: Blocks, snapshot: Snapshot | undefined): Promise<EffectiveSettings> {
210
+ async #settingsOf(blocks: Blocks, snapshot: Snapshot | undefined): Promise<SavedSettings> {
185
211
  if (snapshot === undefined) return defaultSettings(this.#caps);
186
212
  const cached = this.#staticSettings.get(snapshot);
187
213
  if (cached !== undefined) return cached;
@@ -192,6 +218,7 @@ class CMSInstance {
192
218
  load: () => Promise.resolve(snapshot),
193
219
  blocks,
194
220
  builtIns: this.#builtIns,
221
+ date: Date.now(),
195
222
  onCollision: (name) => this.#warnCollision(name),
196
223
  }),
197
224
  this.#caps,
@@ -205,9 +232,14 @@ class CMSInstance {
205
232
  return settings;
206
233
  }
207
234
 
208
- /** Whether the release's preview hosts allow this request's host. */
209
- async #previewAllowed(blocks: Blocks, request: RequestLike): Promise<boolean> {
210
- const { hosts } = (await this.settings(blocks)).preview;
235
+ /**
236
+ * Whether the current release's preview hosts (the release metadata's,
237
+ * read once if this process hasn't yet) or code's allow this request's host.
238
+ * No list published (or no remote site and no code list): every host; a
239
+ * failed read of the metadata: code's list alone (see `previewHosts`).
240
+ */
241
+ async #previewAllowed(request: RequestLike): Promise<boolean> {
242
+ const hosts = previewHosts(await this.#store.previewHosts(), this.#codeHosts);
211
243
  const patterns = hosts
212
244
  .map((raw) => parseHostPattern(raw))
213
245
  .filter((pattern): pattern is HostPattern => pattern !== null);
@@ -235,11 +267,23 @@ class CMSInstance {
235
267
  if (last?.snapshot !== snapshot) await read;
236
268
  }
237
269
 
238
- #client(blocks: Blocks, load: () => Promise<Snapshot>): Client {
270
+ /** A client with its inputs (each client copies its visitor, so none is shared). */
271
+ #client(
272
+ blocks: Blocks,
273
+ load: () => Promise<Snapshot>,
274
+ inputs: {
275
+ version: string | undefined;
276
+ visitor: ClientOptions["visitor"];
277
+ date: number;
278
+ experiments: Overrides | undefined;
279
+ campaigns: Overrides | undefined;
280
+ },
281
+ ): Client {
239
282
  return new CMSClient({
240
283
  load,
241
284
  blocks,
242
285
  builtIns: this.#builtIns,
286
+ ...inputs,
243
287
  onCollision: (name) => this.#warnCollision(name),
244
288
  telemetry: this.#telemetry?.forClient(),
245
289
  });
@@ -292,12 +336,16 @@ class CMSHandle implements CMS {
292
336
  return this.#instance;
293
337
  }
294
338
 
339
+ client(options: ClientOptions = {}): Client {
340
+ return this.#instance.client(this.#blocks, options);
341
+ }
342
+
295
343
  forRelease(): Client {
296
- return this.#instance.forRelease(this.#blocks);
344
+ return this.#instance.client(this.#blocks);
297
345
  }
298
346
 
299
347
  forDraft(pointer: string): Client {
300
- return this.#instance.forDraft(this.#blocks, pointer);
348
+ return this.#instance.client(this.#blocks, { version: pointer });
301
349
  }
302
350
 
303
351
  update(): Promise<{ updated: boolean }> {
@@ -308,12 +356,16 @@ class CMSHandle implements CMS {
308
356
  return this.#instance.settings(this.#blocks);
309
357
  }
310
358
 
311
- draftPointer(request: RequestLike): Promise<string | null> {
312
- return this.#instance.draftPointer(this.#blocks, request);
359
+ readVersion(request: RequestLike): Promise<RequestVersion | null> {
360
+ return this.#instance.readVersion(request);
361
+ }
362
+
363
+ async draftPointer(request: RequestLike): Promise<string | null> {
364
+ return (await this.#instance.readVersion(request))?.version ?? null;
313
365
  }
314
366
 
315
367
  draftCookie(request: RequestLike): Promise<string | null> {
316
- return this.#instance.draftCookie(this.#blocks, request);
368
+ return this.#instance.draftCookie(request);
317
369
  }
318
370
  }
319
371
 
@@ -388,6 +440,19 @@ export function adoptContent(content: Snapshot): number {
388
440
  return adopted;
389
441
  }
390
442
 
443
+ /**
444
+ * A client's own frozen copy of the tests or campaigns it is given: the
445
+ * entries that are `true` or `false`; `undefined` for none.
446
+ */
447
+ function overridesOf(given: unknown): Overrides | undefined {
448
+ if (typeof given !== "object" || given === null || Array.isArray(given)) return undefined;
449
+ const out = Object.create(null) as Record<string, boolean>;
450
+ for (const [name, on] of Object.entries(given as Record<string, unknown>)) {
451
+ if (typeof on === "boolean") out[name] = on;
452
+ }
453
+ return Object.freeze(out);
454
+ }
455
+
391
456
  /** Clears every stored CMS instance, so a test starts clean. */
392
457
  export function resetForTests(): void {
393
458
  clearGlobals(INSTANCE_PREFIX);
package/src/v8/content.ts CHANGED
@@ -50,6 +50,44 @@ export function peekRelease(source: Snapshot | Loader): Snapshot | undefined {
50
50
  return typeof peek === "function" ? peek.call(source) : undefined;
51
51
  }
52
52
 
53
+ /**
54
+ * An internal hook `remoteLoader` has: a published release by its commit SHA
55
+ * (`sites/<site>/revisions/<sha>.json`), kept in memory once read. Rejects
56
+ * with `LOADER_FAILED`, never falls back to another release.
57
+ */
58
+ export const READ_REVISION: unique symbol = Symbol.for("decocms.blocks.readRevision");
59
+
60
+ /**
61
+ * An internal hook `remoteLoader` has: the current release's preview hosts
62
+ * from the release metadata (`latest.json`), read once when this process
63
+ * hasn't read them yet (see `ReleasePreviewHosts`).
64
+ */
65
+ export const PREVIEW_HOSTS: unique symbol = Symbol.for("decocms.blocks.previewHosts");
66
+
67
+ /**
68
+ * What the current release says about where it may be previewed (PO 2026-10-22):
69
+ * - a list: the hosts Studio wrote (`previewHosts`), enforced;
70
+ * - `"every"`: a remote site with no list published, so every host: no
71
+ * `latest.json` yet (a 404), or one without `previewHosts` (published
72
+ * before Studio wrote the list; its next publish writes one);
73
+ * - `"local"`: content with no remote site (no release metadata at all):
74
+ * `createCMS`'s `preview.hosts` when set, else every host;
75
+ * - `"unknown"`: the metadata couldn't be read (a network error, a 5xx, a
76
+ * malformed `latest.json`). That isn't "missing": previews stay closed.
77
+ */
78
+ export type ReleasePreviewHosts = readonly string[] | "every" | "local" | "unknown";
79
+
80
+ /**
81
+ * A release's `previewHosts` as Studio wrote them: the strings of a list;
82
+ * `undefined` when the field is absent (no list written); an empty list (no
83
+ * host) for a field that isn't a list, so a malformed one never opens previews.
84
+ */
85
+ export function previewHostsOf(value: unknown): string[] | undefined {
86
+ if (value === undefined) return undefined;
87
+ if (!Array.isArray(value)) return [];
88
+ return value.filter((host): host is string => typeof host === "string");
89
+ }
90
+
53
91
  export function isSnapshot(content: unknown): content is Snapshot {
54
92
  return (
55
93
  isPlainObject(content) &&
@@ -57,7 +95,8 @@ export function isSnapshot(content: unknown): content is Snapshot {
57
95
  isPlainObject(content.blocks) &&
58
96
  (content.aliases === undefined || isPlainObject(content.aliases)) &&
59
97
  (content.schemaHash === undefined || typeof content.schemaHash === "string") &&
60
- (content.committedAt === undefined || typeof content.committedAt === "string")
98
+ (content.committedAt === undefined || typeof content.committedAt === "string") &&
99
+ (content.previewHosts === undefined || Array.isArray(content.previewHosts))
61
100
  );
62
101
  }
63
102
 
@@ -156,6 +195,31 @@ export class ContentStore {
156
195
  });
157
196
  }
158
197
 
198
+ /**
199
+ * A published release by its commit SHA: from the source's hosted releases
200
+ * (`remoteLoader`, which `createCMS` builds with `site`), or the content in
201
+ * memory when it is that revision. Anything else is `LOADER_FAILED`, never
202
+ * a silent fallback to the current release.
203
+ */
204
+ revision(sha: string): Promise<Snapshot> {
205
+ const source = this.#source;
206
+ const read = isLoader(source)
207
+ ? (source as { [READ_REVISION]?: (sha: string) => Promise<Snapshot> })[READ_REVISION]
208
+ : undefined;
209
+ if (typeof read === "function") {
210
+ return read.call(source, sha).catch((error: unknown) => {
211
+ if (isResolutionError(error)) throw error;
212
+ throw errors.loaderFailed(`the release ${sha} couldn't be read`, error);
213
+ });
214
+ }
215
+ return this.release().then((snapshot) => {
216
+ if (snapshot.revision === sha) return snapshot;
217
+ throw errors.loaderFailed(
218
+ `the release ${sha} isn't available: published releases are read from hosted releases (createCMS with site)`,
219
+ );
220
+ });
221
+ }
222
+
159
223
  /**
160
224
  * The current release as it is in memory, without loading anything: the
161
225
  * content module, what a built-in loader holds, or the release this store
@@ -165,6 +229,26 @@ export class ContentStore {
165
229
  return peekRelease(this.#source) ?? this.#latest;
166
230
  }
167
231
 
232
+ /**
233
+ * The current release's preview hosts (see `ReleasePreviewHosts`): what the
234
+ * source's release metadata says (`remoteLoader` reads it once if it hasn't
235
+ * yet; a failed read is `"unknown"`), else, for a source with no release
236
+ * metadata (no remote site), the release in memory's own `previewHosts`, or
237
+ * `"local"` without one. `peek` reads memory only, never the network.
238
+ */
239
+ async previewHosts(peek = false): Promise<ReleasePreviewHosts> {
240
+ const source = this.#source;
241
+ const read = isLoader(source)
242
+ ? (source as { [PREVIEW_HOSTS]?: (peek: boolean) => Promise<ReleasePreviewHosts> })[
243
+ PREVIEW_HOSTS
244
+ ]
245
+ : undefined;
246
+ if (typeof read === "function") {
247
+ return read.call(source, peek).catch((): ReleasePreviewHosts => "unknown");
248
+ }
249
+ return previewHostsOf(this.current()?.previewHosts) ?? "local";
250
+ }
251
+
168
252
  /** Asks the source for newer content; never throws, and concurrent calls share one check. */
169
253
  update(): Promise<{ updated: boolean }> {
170
254
  const source = this.#source;
@@ -178,7 +262,7 @@ export class ContentStore {
178
262
  if (updated) {
179
263
  this.#release = undefined;
180
264
  // `#latest` stays: settings keep the release that was serving until
181
- // the next one loads, never the defaults (which may allow every host).
265
+ // the next one loads, never the defaults (which allow no host).
182
266
  // Drafts are fetched again, so a preview follows the release too.
183
267
  this.#drafts.clear();
184
268
  }