@avocadostudio-ai/shared 0.5.1 → 0.6.0

package/dist/block-manifest.d.ts

@@ -36,6 +36,8 @@ export declare const fieldMetaSchema: z.ZodObject<{
     }, z.core.$strip>>;
     multiline: z.ZodOptional<z.ZodBoolean>;
     referenceLabelKey: z.ZodOptional<z.ZodString>;
+    panelOnly: z.ZodOptional<z.ZodBoolean>;
+    internal: z.ZodOptional<z.ZodBoolean>;
     inline: z.ZodOptional<z.ZodBoolean>;
     decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -80,6 +82,8 @@ export declare const listFieldMetaSchema: z.ZodObject<{
         }, z.core.$strip>>;
         multiline: z.ZodOptional<z.ZodBoolean>;
         referenceLabelKey: z.ZodOptional<z.ZodString>;
+        panelOnly: z.ZodOptional<z.ZodBoolean>;
+        internal: z.ZodOptional<z.ZodBoolean>;
         inline: z.ZodOptional<z.ZodBoolean>;
         decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -123,6 +127,8 @@ export declare const listFieldMetaSchema: z.ZodObject<{
         }, z.core.$strip>>;
         multiline: z.ZodOptional<z.ZodBoolean>;
         referenceLabelKey: z.ZodOptional<z.ZodString>;
+        panelOnly: z.ZodOptional<z.ZodBoolean>;
+        internal: z.ZodOptional<z.ZodBoolean>;
         inline: z.ZodOptional<z.ZodBoolean>;
         decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -172,6 +178,8 @@ export declare const blockDefinitionSchema: z.ZodObject<{
         }, z.core.$strip>>;
         multiline: z.ZodOptional<z.ZodBoolean>;
         referenceLabelKey: z.ZodOptional<z.ZodString>;
+        panelOnly: z.ZodOptional<z.ZodBoolean>;
+        internal: z.ZodOptional<z.ZodBoolean>;
         inline: z.ZodOptional<z.ZodBoolean>;
         decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -216,6 +224,8 @@ export declare const blockDefinitionSchema: z.ZodObject<{
             }, z.core.$strip>>;
             multiline: z.ZodOptional<z.ZodBoolean>;
             referenceLabelKey: z.ZodOptional<z.ZodString>;
+            panelOnly: z.ZodOptional<z.ZodBoolean>;
+            internal: z.ZodOptional<z.ZodBoolean>;
             inline: z.ZodOptional<z.ZodBoolean>;
             decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -259,6 +269,8 @@ export declare const blockDefinitionSchema: z.ZodObject<{
             }, z.core.$strip>>;
             multiline: z.ZodOptional<z.ZodBoolean>;
             referenceLabelKey: z.ZodOptional<z.ZodString>;
+            panelOnly: z.ZodOptional<z.ZodBoolean>;
+            internal: z.ZodOptional<z.ZodBoolean>;
             inline: z.ZodOptional<z.ZodBoolean>;
             decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -314,6 +326,8 @@ export declare const blockManifestSchema: z.ZodObject<{
             }, z.core.$strip>>;
             multiline: z.ZodOptional<z.ZodBoolean>;
             referenceLabelKey: z.ZodOptional<z.ZodString>;
+            panelOnly: z.ZodOptional<z.ZodBoolean>;
+            internal: z.ZodOptional<z.ZodBoolean>;
             inline: z.ZodOptional<z.ZodBoolean>;
             decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -358,6 +372,8 @@ export declare const blockManifestSchema: z.ZodObject<{
                 }, z.core.$strip>>;
                 multiline: z.ZodOptional<z.ZodBoolean>;
                 referenceLabelKey: z.ZodOptional<z.ZodString>;
+                panelOnly: z.ZodOptional<z.ZodBoolean>;
+                internal: z.ZodOptional<z.ZodBoolean>;
                 inline: z.ZodOptional<z.ZodBoolean>;
                 decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     name: z.ZodString;
@@ -401,6 +417,8 @@ export declare const blockManifestSchema: z.ZodObject<{
                 }, z.core.$strip>>;
                 multiline: z.ZodOptional<z.ZodBoolean>;
                 referenceLabelKey: z.ZodOptional<z.ZodString>;
+                panelOnly: z.ZodOptional<z.ZodBoolean>;
+                internal: z.ZodOptional<z.ZodBoolean>;
                 inline: z.ZodOptional<z.ZodBoolean>;
                 decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     name: z.ZodString;
@@ -466,7 +484,11 @@ export declare function validateManifestDefaultProps(blocks: BlockDefinition[]):
  *
  * - `propsSchema` decides *which* props exist. A declared entry for a key the
  *   schema does not expose is ignored, not added — otherwise a stale manifest
- *   would put a control on a prop the block cannot store.
+ *   would put a control on a prop the block cannot store. The one exception is
+ *   `internal: true`, which adds no control by definition: it is how a site
+ *   names a prop the derivation skipped for being structural (a Contentful
+ *   `sys`, a `__source` snapshot) so the coverage checkers stop reporting it as
+ *   undescribed. Nothing else can be conjured this way.
  * - A declared entry is merged *over* the derived one, key by key, so a site
  *   can supply just `multiline` and keep the label and options that were
  *   inferred for it.

package/dist/block-manifest.js

@@ -61,6 +61,15 @@ export const fieldMetaSchema = z.object({
      * label it and no sign that anything had been declared.
      */
     referenceLabelKey: z.string().optional(),
+    /*
+     * Both of these decide whether a surface *mentions* a field, and every one
+     * of those surfaces is on the far side of this boundary — the panel, the
+     * planner's schema summary, the coverage checkers. A key this schema omits
+     * is stripped rather than rejected, so an undeclared flag here means the
+     * declaration silently does nothing where it was supposed to act.
+     */
+    panelOnly: z.boolean().optional(),
+    internal: z.boolean().optional(),
     inline: z.boolean().optional(),
     decorators: z
         .array(z.object({ name: z.string().min(1), title: z.string().optional() }))
@@ -257,6 +266,29 @@ const FILE_MEDIA_TYPE_RE = /^application\/(?!json\b)|^text\/(?:csv|calendar)\b/i
 function isInternalPropKey(key) {
     return key.startsWith("_");
 }
+/**
+ * The same statement the paragraph above makes, as a field rather than as an
+ * absence.
+ *
+ * These props used to be skipped outright, which kept them out of the panel
+ * and away from the planner — correct, and invisible to everything that reads
+ * the resolved metadata afterwards. `panelCoverage` is the one that noticed:
+ * a prop in the content and in no field set is an `orphan_prop`, and one
+ * Storyblok integration's `_uid` produced **~800 of them**, burying every real
+ * finding under a wall of noise that could not be closed. There was no way to
+ * close it, because "skipped" and "never declared" were the same thing.
+ *
+ * Emitting `internal: true` says it out loud instead. Every surface that must
+ * not mention the prop checks that flag, so nothing about the promise above
+ * changes; what changes is that the checkers can tell a known non-content prop
+ * from an undescribed one.
+ *
+ * `kind` is a formality here — nothing renders the field — so it does not
+ * matter that a `_key` and a `sys` object both come out as `text`.
+ */
+function internalFieldMeta(key) {
+    return { kind: "text", label: labelFromKey(key), internal: true };
+}
 function labelFromKey(key) {
     // ctaText → "CTA text", imageUrl → "Image", logoAlt → "Logo alt",
     // background_image → "Background image", video_url → "Video", src → "Src"
@@ -348,7 +380,11 @@ function deriveItemFields(itemSchema) {
     for (const [key, propSchema] of Object.entries(props)) {
         if (!isObject(propSchema))
             continue;
-        if (isInternalPropKey(key) || isItemIdentityKey(key))
+        if (isInternalPropKey(key)) {
+            fields[key] = internalFieldMeta(key);
+            continue;
+        }
+        if (isItemIdentityKey(key))
             continue;
         // Skip opaque object/array props (they'd render as "[object Object]"), but
         // keep richtext docs — those self-identify and get the richtext editor.
@@ -443,8 +479,10 @@ export function deriveFieldMetaFromSchema(propsSchema) {
     for (const [key, propSchema] of Object.entries(props)) {
         if (!isObject(propSchema))
             continue;
-        if (isInternalPropKey(key))
+        if (isInternalPropKey(key)) {
+            fields[key] = internalFieldMeta(key);
             continue;
+        }
         const type = typeof propSchema.type === "string" ? propSchema.type : undefined;
         // Array of a discriminated union (oneOf/anyOf of object branches) →
         // polymorphic list field: per-branch fields keyed by the discriminant value.
@@ -504,7 +542,11 @@ export function validateManifestDefaultProps(blocks) {
  *
  * - `propsSchema` decides *which* props exist. A declared entry for a key the
  *   schema does not expose is ignored, not added — otherwise a stale manifest
- *   would put a control on a prop the block cannot store.
+ *   would put a control on a prop the block cannot store. The one exception is
+ *   `internal: true`, which adds no control by definition: it is how a site
+ *   names a prop the derivation skipped for being structural (a Contentful
+ *   `sys`, a `__source` snapshot) so the coverage checkers stop reporting it as
+ *   undescribed. Nothing else can be conjured this way.
  * - A declared entry is merged *over* the derived one, key by key, so a site
  *   can supply just `multiline` and keep the label and options that were
  *   inferred for it.
@@ -515,7 +557,20 @@ export function resolveManifestFieldMeta(definition) {
     const resolvedFields = {};
     for (const [key, derived] of Object.entries(fields)) {
         const declared = declaredFields[key];
-        resolvedFields[key] = isObject(declared) ? { ...derived, ...declared } : derived;
+        const merged = isObject(declared) ? { ...derived, ...declared } : derived;
+        // The underscore convention is not negotiable by declaration: a site may
+        // label `_key` or change its kind, and it still may not hand it to a
+        // person, because the value typed there is the address a field-level
+        // publish patches by.
+        resolvedFields[key] = isInternalPropKey(key) ? { ...merged, internal: true } : merged;
+    }
+    for (const [key, declared] of Object.entries(declaredFields)) {
+        if (key in resolvedFields)
+            continue;
+        if (!isObject(declared) || declared.internal !== true)
+            continue;
+        const fm = declared;
+        resolvedFields[key] = { label: labelFromKey(key), ...fm, kind: fm.kind ?? "text" };
     }
     const declaredLists = isObject(definition.listFields) ? definition.listFields : {};
     const resolvedListFields = {};

package/dist/blocks/_registry.d.ts

@@ -116,6 +116,35 @@ export type FieldMeta = {
      * Use this one when there is no element at all.
      */
     panelOnly?: boolean;
+    /**
+     * This prop belongs to the system that stores the content, not to anyone
+     * editing it.
+     *
+     * Storyblok's `_uid`, Contentful's `sys.id`, a `__source` snapshot, a
+     * revision stamp: the publisher needs them, a person must never edit them,
+     * and the planner must never be told they exist. Until this flag there was
+     * no way to say so, so they rode along undeclared — which is not the same as
+     * absent. An undeclared prop is an `orphan_prop` to `panelCoverage`, and one
+     * integration's `_uid` produced **~800 of them**, burying every real finding
+     * under a wall of noise that could not be closed.
+     *
+     * Declaring the prop internal says the opposite of what leaving it out says:
+     * "this is known, it is not content, and nothing that talks to a human or a
+     * model should mention it." Concretely it is hidden from the property panel,
+     * absent from the schema summary the planner reads, not expected to carry a
+     * preview marker, never offered for translation, and not a coverage finding
+     * in either direction — neither an orphan nor a phantom.
+     *
+     * It is not access control. The value still rides in `props`, still
+     * round-trips through the draft, and is still what the adapter writes back;
+     * an operation that names one is refused the way any undeclared prop is,
+     * because the planner was never told about it.
+     *
+     * `panelOnly` is the weaker neighbour and means almost the reverse: *a
+     * person does edit this, just not on the page.* Reach for that one when the
+     * field has no element; reach for this one when the field has no audience.
+     */
+    internal?: boolean;
     /**
      * For `kind: "reference"`: the key inside the value holding something a
      * person can read.

package/dist/editable-coverage.js

@@ -49,6 +49,10 @@ const DRAWN_KINDS = new Set(["text", "richtext", "image"]);
  * button, and the panel offering one is the site saying the image is editable.
  */
 function needsMarker(meta) {
+    // Not content at all — a CMS's `_uid`, a revision stamp. Nobody edits it
+    // anywhere, so there is nothing on the page for it to be missing from.
+    if (meta.internal)
+        return false;
     // The site has said outright that nothing on the page draws this — a
     // `sectionId`, a `<video poster>`, an input's `placeholder`. See `panelOnly`.
     if (meta.panelOnly)
@@ -73,10 +77,19 @@ const VOID_ELEMENTS = new Set([
     "link", "meta", "param", "source", "track", "wbr",
 ]);
 /** One element: its tag name, and the raw attribute text, quotes respected. */
-const TAG_RE = /<([a-zA-Z][\w-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
+const TAG_RE = /<(\/?)([a-zA-Z][\w-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
 const BLOCK_ID_RE = /\bdata-block-id="([^"]*)"/;
 const BLOCK_TYPE_RE = /\bdata-block-type="([^"]*)"/;
 const TARGET_RE = /\bdata-editable-target="([^"]*)"/;
+const SCOPE_RE = /\bdata-editable-scope="([^"]*)"/;
+/** `items[3]` + `question` → `items[3].question`; `cards` + `[0].title` → `cards[0].title`. */
+function joinPath(scope, path) {
+    if (scope === "")
+        return path;
+    if (path === "")
+        return scope;
+    return path.startsWith("[") ? `${scope}${path}` : `${scope}.${path}`;
+}
 /**
  * Read the marked blocks out of a rendered page's HTML.
  *
@@ -90,9 +103,35 @@ const TARGET_RE = /\bdata-editable-target="([^"]*)"/;
 export function extractMarkedBlocks(html) {
     const blocks = [];
     let current = null;
+    /*
+     * The open elements that carry a `data-editable-scope`, innermost last, each
+     * remembered with the tag that will close it. A component rendering a list
+     * row marks a bare `question` and its parent supplies `items[3]`, so the
+     * path this file compares against the manifest exists only as the join —
+     * see `editableScopeProps`. Without the stack a scoped site's every field
+     * reads as missing, and the check that exists to catch a lost marker becomes
+     * the reason nobody runs it.
+     */
+    const scopes = [];
+    const depths = new Map();
     for (const match of html.matchAll(TAG_RE)) {
-        const tag = match[1].toLowerCase();
-        const attrs = match[2] ?? "";
+        const closing = match[1] === "/";
+        const tag = match[2].toLowerCase();
+        const attrs = match[3] ?? "";
+        const selfClosing = attrs.trimEnd().endsWith("/");
+        const isVoid = VOID_ELEMENTS.has(tag);
+        if (closing) {
+            const depth = (depths.get(tag) ?? 0) - 1;
+            depths.set(tag, depth);
+            while (scopes.length > 0) {
+                const top = scopes[scopes.length - 1];
+                if (top.tag === tag && top.depth === depth)
+                    scopes.pop();
+                else
+                    break;
+            }
+            continue;
+        }
         const blockId = BLOCK_ID_RE.exec(attrs)?.[1];
         const blockType = BLOCK_TYPE_RE.exec(attrs)?.[1];
         if (blockId !== undefined || blockType !== undefined) {
@@ -102,13 +141,29 @@ export function extractMarkedBlocks(html) {
                 paths: [],
             };
             blocks.push(current);
+            // A path is scoped from the block down, so a scope opened outside this
+            // block must not reach into it.
+            scopes.length = 0;
         }
         const target = TARGET_RE.exec(attrs)?.[1];
         if (target !== undefined && current) {
-            current.paths.push(target);
-            if (VOID_ELEMENTS.has(tag))
-                (current.voidPaths ??= []).push(target);
+            const path = scopes.reduce((acc, s) => joinPath(acc, s.scope), "");
+            const full = joinPath(path, target);
+            current.paths.push(full);
+            if (isVoid)
+                (current.voidPaths ??= []).push(full);
         }
+        if (isVoid || selfClosing)
+            continue;
+        const depth = depths.get(tag) ?? 0;
+        depths.set(tag, depth + 1);
+        const scope = SCOPE_RE.exec(attrs)?.[1];
+        // The scoping element's own marker is not inside its scope — a component
+        // that both scopes its children and marks a field of its own would
+        // otherwise prefix its own path with the scope it sets for them. That is
+        // why this comes after the target is recorded.
+        if (scope !== undefined && scope !== "")
+            scopes.push({ tag, scope, depth });
     }
     return blocks;
 }

package/dist/panel-coverage.js

@@ -58,7 +58,9 @@ function hasContent(value) {
  * had no way to use it. A finding with no remedy gets switched off.
  */
 export function deriveRowLabel(fields, item, index, options) {
-    const candidates = Object.keys(fields).filter((k) => k !== options?.discriminator);
+    // An internal field is not content — `_uid` is a perfectly good string and
+    // would label every row in the list with a UUID.
+    const candidates = Object.keys(fields).filter((k) => k !== options?.discriminator && !fields[k].internal);
     for (const key of candidates) {
         if (fields[key].kind !== "text" && fields[key].kind !== "richtext")
             continue;
@@ -312,8 +314,12 @@ export function panelCoverage(manifest, pages, options) {
                     }
                     const branchKey = `${block.type}\u0000${listKey}\u0000${discriminantValue}`;
                     let declared = declaredItemKeys.get(branchKey);
-                    if (!declared)
-                        declaredItemKeys.set(branchKey, (declared = new Set(Object.keys(fields))));
+                    if (!declared) {
+                        // An internal field is declared so that the props carrying it stop
+                        // reading as orphans; it is not a promise that a row holds one, so
+                        // it cannot be a phantom either.
+                        declaredItemKeys.set(branchKey, (declared = new Set(Object.keys(fields).filter((k) => !fields[k].internal))));
+                    }
                     let seen = seenItemKeys.get(branchKey);
                     if (!seen)
                         seenItemKeys.set(branchKey, (seen = new Set()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/shared",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/richtext": "^0.5.1"
+    "@avocadostudio-ai/richtext": "^0.6.0"
   },
   "devDependencies": {
     "tsx": "^4.21.0",