@digital-gravy/etch-connector 0.1.2 → 0.1.3

package/dist/cli.js

@@ -437,7 +437,23 @@ changes and training data may be stale):
   Manual fallback           https://docs.etchwp.com/public-api (window.etch.*)
                             https://docs.etchwp.com (everything else)
 
-Building Etch pages (AGENT: conventions for structuring content):
+Building Etch pages (AGENT: conventions — follow these or the builder won't
+render what you author):
+  Images. ALWAYS use the Dynamic Image element (etch/dynamic-image, <etch:img>),
+    NEVER a plain etch/element with tag "img". Bind it by WP media ID, not a URL:
+        attributes: { mediaId: "{props.image}", useSrcSet: "true", alt: "{props.name}" }
+    The backing prop must be a Media prop, not a text prop:
+        type: { primitive: "string", specialized: "wpMediaId" }
+    (specialized "image" is the URL-based picker — NOT for mediaId.) Instances
+    then pass the numeric media ID, e.g. image: "10" — not the file URL.
+
+  Classes. A block's classes ARE its read-only \`styles\` array, not an HTML
+    attribute. Setting attributes.class in authored JSON is silently dropped, and
+    \`styles\` is rejected on authoring. Assign classes with etch.blocks.addClass()
+    — for component blocks, inside enterComponentEditMode() →
+    saveComponentEditModeAsync() → exitComponentEditMode(). An existing class
+    name re-links to its style record automatically (styling is preserved).
+
   Sections. When you create a top-level section, always tag it
     data-etch-element="section" and nest ONE container inside it as its inner —
     a div block with data-etch-element="container" — and put the section's
@@ -453,6 +469,19 @@ Building Etch pages (AGENT: conventions for structuring content):
     side padding, or inter-section margins — the pair already handles layout
     structure, spacing, and content width.
 
+  Gotchas.
+    • NEVER call etch.*.saveAsync (or otherwise persist) unless the user
+      explicitly asks to save — authored changes stay in the builder until then.
+    • Component instance props are attributes: set them at create()/replace()
+      time, or update an existing instance in place with
+          etch.blocks.update(instanceId, { attributes: { image: "10" } })
+    • updateAsync({ blocks }) requires styles:[] on every element block
+      (validation differs from blocks.create(), which omits styles entirely).
+    • No etch.media API. Resolve a URL → media ID via the WP REST API:
+          curl 'http://<site>/?rest_route=/wp/v2/media&per_page=100&_fields=id,source_url'
+      (rest_route form works on plain permalinks; /wp-json/wp/v2/media on pretty
+      ones.)
+
 See AGENTS.md for project conventions.`);
 }
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-connector",
-	"version": "0.1.2",
+	"version": "0.1.3",
 	"publishConfig": {
 		"access": "public"
 	},