ampless 1.0.0-beta.51 → 1.0.0-beta.53

package/dist/index.d.ts

@@ -1829,17 +1829,31 @@ declare function escapeXml(s: string): string;
  *
  *     Variable 'body' has an invalid value.
  *
- * On the read side two wire shapes coexist:
- *
- *   - JSON-encoded string — what the auto-generated CRUD resolver and
- *     custom resolvers usually return.
- *   - Native object / Map — DynamoDBDocumentClient unmarshals
- *     AWSJSON-stored maps straight into JS objects when read directly
- *     from DynamoDB (the path used by the trusted processor and the
- *     MCP Lambda).
- *
- * `decodeAwsJson` handles both: pass strings through `JSON.parse`,
- * everything else as-is.
+ * On the read side there are two FUNDAMENTALLY DIFFERENT paths, and they
+ * must be handled differently — the value's runtime shape is NOT enough
+ * to disambiguate them:
+ *
+ *   1. GraphQL wire read (auto-generated CRUD resolver, custom resolvers,
+ *      raw GraphQL fetch) — the value arrives as a JSON-encoded string,
+ *      regardless of the underlying type. Use `decodeAwsJson` to parse it
+ *      back into the native JS value.
+ *
+ *   2. Direct DynamoDBDocumentClient read (the trusted processor and the
+ *      MCP Lambda read straight from DynamoDB) — DocumentClient already
+ *      unmarshals AWSJSON-backed attributes into native JS types
+ *      (S→string, N→number, BOOL→boolean, M→object). The value is ALREADY
+ *      the correct JS type and must be used AS-IS. Do NOT run
+ *      `decodeAwsJson` / `JSON.parse` on it.
+ *
+ * Why the distinction is load-bearing: a native scalar STRING from path 2
+ * is indistinguishable, by type alone, from a wire string on path 1. But
+ * `decodeAwsJson("1470")` === `JSON.parse("1470")` === the number `1470`,
+ * so running the decoder on a DocumentClient scalar string silently
+ * double-decodes numeric-looking settings/bodies (this caused a
+ * site-wide 500). The "non-strings pass through unchanged" tolerance of
+ * `decodeAwsJson` does NOT make it safe on DocumentClient reads — scalar
+ * strings are exactly the case it corrupts. Pick the decoder by read PATH,
+ * never by the value's runtime shape.
  */
 /**
  * Serialise a value for an AWSJSON variable. `undefined` / `null` both
@@ -1848,9 +1862,14 @@ declare function escapeXml(s: string): string;
  */
 declare function encodeAwsJson(value: unknown): string;
 /**
- * Deserialise an AWSJSON value from a GraphQL / DynamoDB read.
- * Tolerates both the wire-string shape and the auto-unmarshalled
- * native value. Throws if the string is not valid JSON.
+ * Deserialise an AWSJSON value from a GraphQL wire read (path 1 above).
+ * Non-string inputs pass through unchanged; strings go through
+ * `JSON.parse` and throw if not valid JSON.
+ *
+ * Only call this on values read over the GraphQL wire. Do NOT call it on
+ * values read directly via DynamoDBDocumentClient — those are already
+ * native JS types, and a native scalar string (e.g. "1470") would be
+ * double-decoded into a number. See the module doc block above.
  */
 declare function decodeAwsJson(value: unknown): unknown;
 

package/docs/plugin-author-guide.ja.md

@@ -481,6 +481,15 @@ runtime は `body` を `sanitize-html` の厳格 allowlist で sanitize し（
 
 `cms.config.plugins` の順序は集約後も保たれます。
 
+> **`publicHead` / `publicBodyEnd` はいつ描画される？**
+> runtime は、ampless middleware が処理した公開リクエストでのみ
+> これらのサーフェスの出力を描画します。`/admin`、`/login`、
+> そして theme preview リクエスト（`?previewTheme=` /
+> `?previewColorScheme=` iframe）では描画されません。これにより、
+> GTM / GA / consent script が admin page view や live preview traffic で
+> analytics を汚染することを防ぎます。この挙動は
+> `@ampless/runtime` の npm update だけで反映され、サイトコードの変更は不要です。
+
 ### `publicBodyForPost` の使用例（Phase 4）
 
 `schema` capability を宣言してサーフェスを実装します：

package/docs/plugin-author-guide.md

@@ -603,6 +603,16 @@ interpolates that fragment directly:
 `cms.config.plugins` iteration order is preserved across the
 collected list.
 
+> **When are `publicHead` / `publicBodyEnd` rendered?**
+> The runtime renders output from these surfaces only on public requests
+> that have been processed by the ampless middleware. They are **not**
+> rendered under `/admin`, `/login`, or on theme-preview requests
+> (`?previewTheme=` / `?previewColorScheme=` iframe). This prevents GTM,
+> GA, and consent scripts from polluting analytics with admin page views
+> or live-preview traffic. An npm update to `@ampless/runtime` is
+> sufficient to pick up this behaviour — no changes to site code are
+> required.
+
 ### `publicBodyForPost` example (Phase 4)
 
 Declare the `schema` capability and implement the surface:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-beta.51",
+  "version": "1.0.0-beta.53",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",