@avocadostudio-ai/shared 0.3.1 → 0.3.3

package/dist/api-responses.d.ts

@@ -52,6 +52,11 @@ export declare const chatStartResponseSchema: z.ZodObject<{
 }, z.core.$loose>;
 export declare const slugsResponseSchema: z.ZodObject<{
     slugs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 export declare const bootstrapResponseSchema: z.ZodObject<{
     slugs: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/api-responses.js

@@ -58,6 +58,18 @@ export const chatStartResponseSchema = z.object({
 }).passthrough();
 export const slugsResponseSchema = z.object({
     slugs: z.array(z.string()).optional(),
+    /*
+     * The same pages the `slugs` array names, with the title and the URL that
+     * `/draft/slugs` has always returned beside them. The editor parsed this
+     * response and kept only the bare slugs, so the link picker had nothing to
+     * label a page with; `path` is what a locale-prefixed site navigates to when
+     * it differs from the slug (see docs/ideas/page-identity-punch-list.md).
+     */
+    pages: z.array(z.object({
+        slug: z.string(),
+        path: z.string().optional(),
+        title: z.string().optional(),
+    }).passthrough()).optional(),
 }).passthrough();
 export const bootstrapResponseSchema = z.object({
     slugs: z.array(z.string()).optional(),

package/dist/block-manifest.d.ts

@@ -19,6 +19,7 @@ export declare const fieldMetaSchema: z.ZodObject<{
         text: "text";
         richtext: "richtext";
         url: "url";
+        link: "link";
         image: "image";
         imageAlt: "imageAlt";
         color: "color";
@@ -59,6 +60,7 @@ export declare const listFieldMetaSchema: z.ZodObject<{
             text: "text";
             richtext: "richtext";
             url: "url";
+            link: "link";
             image: "image";
             imageAlt: "imageAlt";
             color: "color";
@@ -98,6 +100,7 @@ export declare const listFieldMetaSchema: z.ZodObject<{
             text: "text";
             richtext: "richtext";
             url: "url";
+            link: "link";
             image: "image";
             imageAlt: "imageAlt";
             color: "color";
@@ -143,6 +146,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
             text: "text";
             richtext: "richtext";
             url: "url";
+            link: "link";
             image: "image";
             imageAlt: "imageAlt";
             color: "color";
@@ -183,6 +187,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
                 text: "text";
                 richtext: "richtext";
                 url: "url";
+                link: "link";
                 image: "image";
                 imageAlt: "imageAlt";
                 color: "color";
@@ -222,6 +227,7 @@ export declare const blockDefinitionSchema: z.ZodObject<{
                 text: "text";
                 richtext: "richtext";
                 url: "url";
+                link: "link";
                 image: "image";
                 imageAlt: "imageAlt";
                 color: "color";
@@ -273,6 +279,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                 text: "text";
                 richtext: "richtext";
                 url: "url";
+                link: "link";
                 image: "image";
                 imageAlt: "imageAlt";
                 color: "color";
@@ -313,6 +320,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                     text: "text";
                     richtext: "richtext";
                     url: "url";
+                    link: "link";
                     image: "image";
                     imageAlt: "imageAlt";
                     color: "color";
@@ -352,6 +360,7 @@ export declare const blockManifestSchema: z.ZodObject<{
                     text: "text";
                     richtext: "richtext";
                     url: "url";
+                    link: "link";
                     image: "image";
                     imageAlt: "imageAlt";
                     color: "color";

package/dist/block-manifest.js

@@ -24,7 +24,7 @@ export const jsonSchemaLikeSchema = z.lazy(() => z.object({
  * JSON Schema spelling, so they have to travel beside it.
  */
 export const fieldMetaSchema = z.object({
-    kind: z.enum(["text", "richtext", "url", "image", "imageAlt", "enum", "color", "number", "boolean", "headingLevel"]),
+    kind: z.enum(["text", "richtext", "url", "link", "image", "imageAlt", "enum", "color", "number", "boolean", "headingLevel"]),
     label: z.string().optional(),
     inlineEditable: z.boolean().optional(),
     options: z.array(z.string()).optional(),
@@ -184,6 +184,7 @@ export function validateByJsonSchemaLike(schema, value) {
 // ---------------------------------------------------------------------------
 const IMAGE_KEY_RE = /(?:image|img)(?:Url|Src)?$|^(?:src|imageUrl|logoUrl|heroImage)$/i;
 const IMAGE_ALT_KEY_RE = /(?:Alt)$/;
+const LINK_KEY_RE = /(?:href|link)$/i;
 function labelFromKey(key) {
     // ctaText → "CTA text", imageUrl → "Image", logoAlt → "Logo alt",
     // background_image → "Background image", video_url → "Video", src → "Src"
@@ -224,6 +225,14 @@ function inferFieldKind(key, schema) {
         return "imageAlt";
     if (IMAGE_KEY_RE.test(key))
         return "image";
+    /*
+     * A custom block's `ctaHref` is a link, and inferring it as plain text gave
+     * an integrator's editors a bare box where the built-in blocks get a page
+     * picker. Checked after the image patterns so `imageUrl` and `logoUrl` still
+     * resolve to images — those end in "Url" too.
+     */
+    if (LINK_KEY_RE.test(key))
+        return "link";
     return "text";
 }
 function deriveItemFields(itemSchema) {

package/dist/blocks/_helpers.d.ts

@@ -3,7 +3,16 @@ export declare const f: {
     readonly text: (label?: string) => FieldMeta;
     readonly longtext: (label?: string) => FieldMeta;
     readonly richtext: (label?: string) => FieldMeta;
+    /** A resource address — an iframe src, a video file. Never an internal page. */
     readonly url: (label?: string) => FieldMeta;
+    /** A navigation target: an internal page, or an external URL / mailto / tel / anchor. */
+    readonly link: (label?: string) => FieldMeta;
+    /**
+     * The "open in new tab" companion for a link prop. Named by convention
+     * (`newTabKeyFor`) so the property panel renders it inside the link control
+     * rather than as a row of its own — the same pairing as `image`/`imageAlt`.
+     */
+    readonly newTab: (label?: string) => FieldMeta;
     readonly image: (label?: string, imageSpec?: ImageSpec) => FieldMeta;
     readonly imageAlt: (label?: string) => FieldMeta;
     readonly headingLevel: () => FieldMeta;

package/dist/blocks/_helpers.js

@@ -2,7 +2,16 @@ export const f = {
     text: (label) => ({ kind: "text", label }),
     longtext: (label) => ({ kind: "text", label, multiline: true }),
     richtext: (label) => ({ kind: "richtext", label }),
+    /** A resource address — an iframe src, a video file. Never an internal page. */
     url: (label) => ({ kind: "url", label, inlineEditable: false }),
+    /** A navigation target: an internal page, or an external URL / mailto / tel / anchor. */
+    link: (label) => ({ kind: "link", label, inlineEditable: false }),
+    /**
+     * The "open in new tab" companion for a link prop. Named by convention
+     * (`newTabKeyFor`) so the property panel renders it inside the link control
+     * rather than as a row of its own — the same pairing as `image`/`imageAlt`.
+     */
+    newTab: (label = "Open in new tab") => ({ kind: "boolean", label, inlineEditable: false }),
     image: (label, imageSpec) => ({ kind: "image", label, inlineEditable: false, ...(imageSpec ? { imageSpec } : {}) }),
     imageAlt: (label) => ({ kind: "imageAlt", label }),
     headingLevel: () => ({ kind: "headingLevel", label: "Heading type", inlineEditable: false }),

package/dist/blocks/_registry.d.ts

@@ -1,8 +1,17 @@
 import { z } from "zod";
 export declare const IMAGE_PLACEHOLDER = "/hero-generated.svg";
 export declare function isImagePlaceholder(url: string | undefined | null): boolean;
-/** Semantic kind for a block prop field. */
-export type FieldKind = "text" | "richtext" | "url" | "image" | "imageAlt" | "enum" | "color" | "number" | "boolean" | "headingLevel";
+/**
+ * Semantic kind for a block prop field.
+ *
+ * `link` and `url` are both href-valued strings and deliberately distinct.
+ * `link` is a *navigation target* — it may address a page on this site, so it
+ * gets the page picker, the dead-route warning, and the rename rewriter.
+ * `url` is a *resource address* — an embed's iframe src, a video file, an OG
+ * image — which is never an internal page, and where offering a list of pages
+ * would be noise.
+ */
+export type FieldKind = "text" | "richtext" | "url" | "link" | "image" | "imageAlt" | "enum" | "color" | "number" | "boolean" | "headingLevel";
 /** Recommended image dimensions for an image field. */
 export type ImageSpec = {
     aspectRatio: "landscape" | "square" | "portrait";
@@ -108,6 +117,22 @@ export declare function getAllBlockMeta(): Readonly<Record<string, BlockMeta>>;
 export declare function getImageFields(blockType: string): Set<string>;
 /** Get list props that contain image fields: Map<listKey, Set<imageFieldKey>>. */
 export declare function getListImageFields(blockType: string): Map<string, Set<string>>;
+/**
+ * Every prop key on a block type that addresses a *resource* rather than a page
+ * — images, iframe sources, video files — at any depth, scalar and list-item
+ * props flattened into one set.
+ *
+ * Renaming a page rewrites the links that point at it, and the rewriter cannot
+ * tell a link from any other string: it walks the props and remaps every value
+ * that starts with the old slug. That silently rewrote `/pricing/demo.mp4` into
+ * `/plans/demo.mp4` on a rename — an asset path is not a route, and renaming a
+ * page does not move the file. This set is what the walker skips.
+ *
+ * It is an exclusion rather than a `kind: "link"` allow-list on purpose: a
+ * custom block that ships no field metadata still has its links rewritten, the
+ * way it always did.
+ */
+export declare function getMediaFields(blockType: string): Set<string>;
 /** Check if a block type is a chrome block (structurally pinned). */
 export declare function isChrome(type: string): boolean;
 /** Get all registered chrome block type names. */

package/dist/blocks/_registry.js

@@ -182,6 +182,46 @@ export function getListImageFields(blockType) {
     _listImageFieldsCache.set(blockType, result);
     return result;
 }
+/** Cache for getMediaFields results. */
+const _mediaFieldsCache = new Map();
+/**
+ * Every prop key on a block type that addresses a *resource* rather than a page
+ * — images, iframe sources, video files — at any depth, scalar and list-item
+ * props flattened into one set.
+ *
+ * Renaming a page rewrites the links that point at it, and the rewriter cannot
+ * tell a link from any other string: it walks the props and remaps every value
+ * that starts with the old slug. That silently rewrote `/pricing/demo.mp4` into
+ * `/plans/demo.mp4` on a rename — an asset path is not a route, and renaming a
+ * page does not move the file. This set is what the walker skips.
+ *
+ * It is an exclusion rather than a `kind: "link"` allow-list on purpose: a
+ * custom block that ships no field metadata still has its links rewritten, the
+ * way it always did.
+ */
+export function getMediaFields(blockType) {
+    const cached = _mediaFieldsCache.get(blockType);
+    if (cached)
+        return cached;
+    const meta = _blockMeta[blockType];
+    const result = new Set();
+    const collect = (fields) => {
+        for (const [key, fm] of Object.entries(fields)) {
+            if (fm.kind === "image" || fm.kind === "url")
+                result.add(key);
+        }
+    };
+    if (meta) {
+        collect(meta.fields);
+        for (const listMeta of Object.values(meta.listFields ?? {})) {
+            collect(listMeta.itemFields);
+            for (const branch of Object.values(listMeta.itemFieldsByType ?? {}))
+                collect(branch);
+        }
+    }
+    _mediaFieldsCache.set(blockType, result);
+    return result;
+}
 /** Check if a block type is a chrome block (structurally pinned). */
 export function isChrome(type) {
     return _blockMeta[type]?.chrome === true;
@@ -332,7 +372,7 @@ function defaultScalarForField(field, fieldKey) {
     const label = field.label?.trim() || fieldKey;
     if (field.kind === "text" || field.kind === "richtext" || field.kind === "imageAlt")
         return `New ${label}`;
-    if (field.kind === "url")
+    if (field.kind === "url" || field.kind === "link")
         return "/";
     if (field.kind === "image")
         return IMAGE_PLACEHOLDER;
@@ -340,6 +380,14 @@ function defaultScalarForField(field, fieldKey) {
         return "#0f766e";
     if (field.kind === "number")
         return 0;
+    /*
+     * Without this a boolean item field seeded a *string* ("New Open in new tab")
+     * into a new list item, which the block's own zod schema then rejected — the
+     * add-item op failed on a value this function produced. Latent until link
+     * fields introduced the first boolean inside a list.
+     */
+    if (field.kind === "boolean")
+        return false;
     if (field.kind === "enum")
         return Array.isArray(field.options) && field.options.length > 0 ? field.options[0] : "";
     return `New ${label}`;

package/dist/blocks/banner.js

@@ -7,6 +7,7 @@ registerBlock("Banner", {
         variant: z.enum(["info", "success", "warning"]).default("info").catch("info"),
         ctaText: z.string().optional(),
         ctaHref: z.string().optional(),
+        ctaNewTab: z.boolean().optional(),
         backgroundColor: z.string().optional(),
         textColor: z.string().optional(),
     }),
@@ -18,7 +19,8 @@ registerBlock("Banner", {
             text: f.text("Banner text"),
             variant: { kind: "enum", label: "Variant", options: ["info", "success", "warning"], inlineEditable: false },
             ctaText: f.text("Button label"),
-            ctaHref: f.url("Button link"),
+            ctaHref: f.link("Button link"),
+            ctaNewTab: f.newTab(),
             backgroundColor: { kind: "color", label: "Background color", inlineEditable: false },
             textColor: { kind: "color", label: "Text color", inlineEditable: false },
         },

package/dist/blocks/card-grid.js

@@ -14,6 +14,7 @@ registerBlock("CardGrid", {
             description: z.string().min(1),
             ctaText: z.string().min(1),
             ctaHref: z.string().min(1),
+            ctaNewTab: z.boolean().optional(),
             imageUrl: z.string().min(1).optional(),
             imageAlt: z.string().min(1).optional()
         }))
@@ -37,7 +38,8 @@ registerBlock("CardGrid", {
                     title: f.text("Card title"),
                     description: f.longtext("Card description"),
                     ctaText: f.text("Button text"),
-                    ctaHref: f.url("Button link"),
+                    ctaHref: f.link("Button link"),
+                    ctaNewTab: f.newTab(),
                     imageUrl: f.image("Card image", { aspectRatio: "landscape", width: 768, height: 512 }),
                     imageAlt: f.imageAlt("Card image alt text"),
                 }

package/dist/blocks/card.js

@@ -7,6 +7,7 @@ registerBlock("Card", {
         description: z.string().min(1),
         ctaText: z.string().min(1),
         ctaHref: z.string().min(1),
+        ctaNewTab: z.boolean().optional(),
         imageUrl: z.string().min(1).optional(),
         imageAlt: z.string().min(1).optional(),
         variant: z.enum(["default", "full-bleed"]).default("default").catch("default"),
@@ -19,7 +20,8 @@ registerBlock("Card", {
             title: f.text("Card title"),
             description: f.longtext("Card description"),
             ctaText: f.text("Button text"),
-            ctaHref: f.url("Button link"),
+            ctaHref: f.link("Button link"),
+            ctaNewTab: f.newTab(),
             imageUrl: f.image("Card image", { aspectRatio: "landscape", width: 768, height: 512 }),
             imageAlt: f.imageAlt("Card image alt text"),
             variant: { kind: "enum", label: "Variant", options: ["default", "full-bleed"], inlineEditable: false },

package/dist/blocks/carousel.js

@@ -11,6 +11,7 @@ registerBlock("Carousel", {
             description: z.string().optional(),
             ctaText: z.string().optional(),
             ctaHref: z.string().optional(),
+            ctaNewTab: z.boolean().optional(),
         })).min(1),
         autoplay: z.enum(["true", "false"]).default("false").catch("false"),
         interval: z.number().optional(),
@@ -32,7 +33,8 @@ registerBlock("Carousel", {
                     heading: f.text("Heading"),
                     description: f.longtext("Description"),
                     ctaText: f.text("Button label"),
-                    ctaHref: f.url("Button link"),
+                    ctaHref: f.link("Button link"),
+                    ctaNewTab: f.newTab(),
                 }
             }
         }

package/dist/blocks/cta.js

@@ -7,8 +7,10 @@ registerBlock("CTA", {
         description: z.string().min(1),
         ctaText: z.string().min(1),
         ctaHref: z.string().min(1),
+        ctaNewTab: z.boolean().optional(),
         secondaryCtaText: z.string().optional(),
-        secondaryCtaHref: z.string().optional()
+        secondaryCtaHref: z.string().optional(),
+        secondaryCtaNewTab: z.boolean().optional()
     }),
     meta: {
         displayName: "Call to Action",
@@ -18,9 +20,11 @@ registerBlock("CTA", {
             title: f.text("Headline"),
             description: f.longtext("Description"),
             ctaText: f.text("Button text"),
-            ctaHref: f.url("Button link"),
+            ctaHref: f.link("Button link"),
+            ctaNewTab: f.newTab(),
             secondaryCtaText: f.text("Secondary button text"),
-            secondaryCtaHref: f.url("Secondary button link"),
+            secondaryCtaHref: f.link("Secondary button link"),
+            secondaryCtaNewTab: f.newTab(),
             headingLevel: f.headingLevel(),
         }
     }

package/dist/blocks/hero.js

@@ -7,13 +7,15 @@ registerBlock("Hero", {
         subheading: z.string().min(1),
         ctaText: z.string().min(1),
         ctaHref: z.string().min(1),
+        ctaNewTab: z.boolean().optional(),
         imageUrl: z.string().min(1),
         imageAlt: z.string().min(1),
         imagePosition: z.enum(["left", "right", "full"]).default("right").catch("right"),
         textAlign: z.enum(["left", "center"]).default("left").catch("left"),
         eyebrow: z.string().optional(),
         secondaryCtaText: z.string().optional(),
-        secondaryCtaHref: z.string().optional()
+        secondaryCtaHref: z.string().optional(),
+        secondaryCtaNewTab: z.boolean().optional()
     }),
     meta: {
         displayName: "Hero",
@@ -23,14 +25,16 @@ registerBlock("Hero", {
             heading: f.text("Heading"),
             subheading: f.text("Subheading"),
             ctaText: f.text("CTA button text"),
-            ctaHref: f.url("CTA link"),
+            ctaHref: f.link("CTA link"),
+            ctaNewTab: f.newTab(),
             imageUrl: f.image("Hero image", { aspectRatio: "landscape", width: 1536, height: 1024 }),
             imageAlt: f.imageAlt("Hero image alt text"),
             imagePosition: { kind: "enum", label: "Image position", options: ["left", "right", "full"], inlineEditable: false },
             textAlign: { kind: "enum", label: "Text alignment", options: ["left", "center"], inlineEditable: false },
             eyebrow: f.text("Eyebrow text"),
             secondaryCtaText: f.text("Secondary CTA text"),
-            secondaryCtaHref: f.url("Secondary CTA link"),
+            secondaryCtaHref: f.link("Secondary CTA link"),
+            secondaryCtaNewTab: f.newTab(),
             headingLevel: f.headingLevel(),
         }
     }

package/dist/blocks/site-header.js

@@ -5,6 +5,7 @@ const navLinkLeaf = z.object({
     id: z.string().optional(),
     label: z.string().min(1),
     href: z.string().min(1),
+    newTab: z.boolean().optional(),
 });
 registerBlock("SiteHeader", {
     schema: z.object({
@@ -29,7 +30,8 @@ registerBlock("SiteHeader", {
                 label: "Nav links",
                 itemFields: {
                     label: f.text("Link label"),
-                    href: f.url("Link URL"),
+                    href: f.link("Link URL"),
+                    newTab: f.newTab(),
                 },
             },
         },

package/dist/blocks/table.js

@@ -16,8 +16,11 @@ registerBlock("Table", {
         fields: {
             title: f.text("Section title"),
             headingLevel: f.headingLevel(),
-            headers: f.text("Column headers"),
-            rows: f.text("Table rows"),
+            // Both are lists of scalars, which `FieldKind` cannot name — the panel
+            // recognises the value's shape instead: `headers` edits one per line,
+            // `rows` (string[][]) is shown there and edited cell-by-cell in the page.
+            headers: f.text("Column headers (one per line)"),
+            rows: f.text("Table rows (edit cells in the page)"),
             striped: { kind: "enum", label: "Striped rows", options: ["true", "false"], inlineEditable: false },
         },
     }

package/dist/blocks/two-column.js

@@ -10,6 +10,7 @@ const twoColumnChild = z.object({
     text: z.string().optional(),
     label: z.string().optional(),
     href: z.string().optional(),
+    newTab: z.boolean().optional(),
     src: z.string().optional(),
     alt: z.string().optional(),
     poster: z.string().optional(),
@@ -21,7 +22,8 @@ const twoColumnItemFields = {
     type: { kind: "enum", label: "Component type", options: ["heading", "subheading", "paragraph", "list", "cta", "ctas", "image", "video"] },
     text: f.longtext("Text content"),
     label: f.text("Button label"),
-    href: f.url("Link URL"),
+    href: f.link("Link URL"),
+    newTab: f.newTab(),
     src: f.image("Media source", { aspectRatio: "portrait", width: 768, height: 1024 }),
     alt: f.imageAlt("Alt text"),
     poster: f.image("Video poster image", { aspectRatio: "landscape", width: 768, height: 512 }),

package/dist/editable-path.d.ts

@@ -7,6 +7,17 @@
 export declare function isImagePath(editablePath: string): boolean;
 /** Derives the companion alt-text path from an image path. Returns the path unchanged if it is not an image path. */
 export declare function toAltPath(editablePath: string): string;
+/** Returns true if the editable path points to an image's alt text. */
+export declare function isAltPath(editablePath: string): boolean;
+/**
+ * Derives the image path an alt-text path belongs to — the inverse of
+ * `toAltPath`. Returns the path unchanged if it is not an alt path.
+ *
+ * Alt text has no node of its own in a rendered page: it is an attribute on the
+ * image. Anything that wants to *show* somebody where an alt-text problem is
+ * has to point at the image instead, and this is the only step between the two.
+ */
+export declare function toImagePath(editablePath: string): string;
 /**
  * Return a copy of `props` with `value` written at `editablePath`, using
  * copy-on-write so the input (and every untouched subtree) is shared by reference.

package/dist/editable-path.js

@@ -13,6 +13,23 @@ export function isImagePath(editablePath) {
 export function toAltPath(editablePath) {
     return editablePath.replace(/imageUrl$/i, "imageAlt").replace(/\.src$/i, ".alt");
 }
+/** Matches editable paths that point to an image's alt text. */
+const ALT_PATH_RE = /(imageAlt|\.alt)$/i;
+/** Returns true if the editable path points to an image's alt text. */
+export function isAltPath(editablePath) {
+    return ALT_PATH_RE.test(editablePath);
+}
+/**
+ * Derives the image path an alt-text path belongs to — the inverse of
+ * `toAltPath`. Returns the path unchanged if it is not an alt path.
+ *
+ * Alt text has no node of its own in a rendered page: it is an attribute on the
+ * image. Anything that wants to *show* somebody where an alt-text problem is
+ * has to point at the image instead, and this is the only step between the two.
+ */
+export function toImagePath(editablePath) {
+    return editablePath.replace(/imageAlt$/i, "imageUrl").replace(/\.alt$/i, ".src");
+}
 /**
  * Parse an editable-target path into a flat list of access steps.
  *

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 export { EDITOR_PROTOCOL_VERSION } from "./protocol.ts";
 export { getConfiguredDraftSecret, getSafeInternalRedirectPath, validateDraftSecret, type DraftSecretValidationResult } from "./draft-mode.ts";
 export type { FieldDiffKind, FieldDiff, BlockDiffStatus, BlockDiff, PageDiffStatus, PageDiff, PublishDiff, SiteConfigFieldDiff, SiteConfigDiff, } from "./publish-diff.ts";
-export { isImagePath, toAltPath, setPropAtPath } from "./editable-path.ts";
+export { isImagePath, toAltPath, isAltPath, toImagePath, setPropAtPath } from "./editable-path.ts";
+export { parseLink, resolveLink, normalizeLinkPath, isKnownRoute, internalPathForUrl, rankLinkTargets, scoreLinkCandidate, suggestLinkTarget, newTabKeyFor, linkAttrs, type LinkKind, type ParsedLink, type ResolvedLink, type LinkPageOption, } from "./links.ts";
 export { parseInline, parseRichText, parseRichTextBlocks, normalizeRichTextBody, resolveRichTextHeadingLevel, clampMarkdownHeadings, unescapeMarkdownText, isRichTextDoc, fromMarkdown, toMarkdown, mergeRichTextDoc, NODE, MARK, type InlineToken, type RichTextBlock, type RichTextList, type RichTextListItem, type RichTextDoc, type RichTextNode, type RichTextMark } from "@avocadostudio-ai/richtext";
 export { blockDefinitionSchema, blockManifestSchema, buildBlockManifest, jsonSchemaLikeSchema, validateByJsonSchemaLike, findManifestSchemaIssue, type ManifestSchemaIssue, validateManifestDefaultProps, deriveFieldMetaFromSchema, resolveManifestFieldMeta, isProseMirrorDocSchema, type BlockDefinition, type BlockManifest } from "./block-manifest.ts";
 export { z } from "zod";
-export { type FieldKind, type ImageSpec, type FieldMeta, type ListFieldMeta, type BlockMeta, type BlockType, type BlockInstance, type BlockRegistration, IMAGE_PLACEHOLDER, isImagePlaceholder, registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, blockSchemas, allowedBlockTypes, declareBlockCatalogue, getBlockCatalogue, isInBlockCatalogue, catalogueBlockTypes, undeclaredBlockTypes, getPropDisplayName, defaultListItemForBlock, blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.ts";
+export { type FieldKind, type ImageSpec, type FieldMeta, type ListFieldMeta, type BlockMeta, type BlockType, type BlockInstance, type BlockRegistration, IMAGE_PLACEHOLDER, isImagePlaceholder, registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, blockSchemas, allowedBlockTypes, declareBlockCatalogue, getBlockCatalogue, isInBlockCatalogue, catalogueBlockTypes, undeclaredBlockTypes, getPropDisplayName, defaultListItemForBlock, blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.ts";
 export { defaultPropsForType, declaredDefaultPropsForType, resolveHeadingTag, resolveItemHeadingTag, DEFAULT_HEADING_LEVELS, } from "./blocks/index.ts";
 export { blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "./block-names.ts";
 export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, type AddBlockOp, type MakeAddBlockOptions, type AddItemOp, type MakeAddItemOptions, } from "./ops/builders.ts";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { EDITOR_PROTOCOL_VERSION } from "./protocol.js";
 export { getConfiguredDraftSecret, getSafeInternalRedirectPath, validateDraftSecret } from "./draft-mode.js";
-export { isImagePath, toAltPath, setPropAtPath } from "./editable-path.js";
+export { isImagePath, toAltPath, isAltPath, toImagePath, setPropAtPath } from "./editable-path.js";
+export { parseLink, resolveLink, normalizeLinkPath, isKnownRoute, internalPathForUrl, rankLinkTargets, scoreLinkCandidate, suggestLinkTarget, newTabKeyFor, linkAttrs, } from "./links.js";
 /*
  * The rich-text grammar lives in `@avocadostudio-ai/richtext`, which owns the
  * parser and every CMS converter and has no dependencies of its own. It is
@@ -33,7 +34,7 @@ export {
 // Constants & helpers
 IMAGE_PLACEHOLDER, isImagePlaceholder, 
 // Registry functions
-registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
+registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
 // Backwards-compatible exports
 blockSchemas, allowedBlockTypes, 
 // The catalogue a site actually renders — see `declareBlockCatalogue`

package/dist/links.d.ts

@@ -0,0 +1,122 @@
+/**
+ * What a link field's string actually means.
+ *
+ * A link is stored as a plain string — `/pricing`, `https://example.com`,
+ * `mailto:hi@example.com` — and three places need to agree on how to read it:
+ * the editor's link control (which icon, which label, which warning), the
+ * `seo.internal-link-dead` check (is this route real?), and the rename rewriter
+ * (is this string a route at all?). Before this module each answered the
+ * question with its own inline `startsWith("/")`, and they did not agree: the
+ * rename rewriter matched on prop *names* containing "href", so a link stored
+ * under `url` or inside Footer's `label|url` text went stale on every rename.
+ *
+ * Nothing here validates in the blocking sense. A path this module cannot
+ * resolve is still a legitimate link — on a CMS-backed site Avocado sees only
+ * the pages it was handed, and a route can exist in Next, in the CMS, or behind
+ * a rewrite and be invisible from here. `resolveLink` reports what it knows; it
+ * never decides what the editor may type.
+ */
+/** How a link string addresses its target. */
+export type LinkKind = "empty" | "page" | "external" | "email" | "phone" | "anchor";
+/** A link string, classified. */
+export type ParsedLink = {
+    kind: LinkKind;
+    /** The original string, untouched. */
+    raw: string;
+    /**
+     * The route, for `kind: "page"` — path only, with `?query` and `#fragment`
+     * stripped. This is what `resolveLink` matches against the site's slugs.
+     */
+    path?: string;
+    /** The `?a=b#c` tail of a page link, preserved so a rewrite can restore it. */
+    suffix?: string;
+    /** Host for `external`, address for `email`, number for `phone`, id for `anchor`. */
+    target?: string;
+};
+/** A page the editor can offer as a link target. */
+export type LinkPageOption = {
+    slug: string;
+    /** The URL, when the site says it differs from the slug (locale prefixes). */
+    path?: string;
+    title?: string;
+};
+/** Classify a link string. Never throws; anything unrecognised parses as `page`-ish text. */
+export declare function parseLink(value: unknown): ParsedLink;
+/**
+ * Give a route its leading slash and drop a trailing one.
+ *
+ * `pricing`, `/pricing`, `/pricing/` are the same page. The editor accepts all
+ * three and stores the middle one. The homepage keeps its lone slash.
+ */
+export declare function normalizeLinkPath(path: string): string;
+/**
+ * Does this route exist among the site's known pages?
+ *
+ * Compares on the path alone — a link may legitimately carry a query or a
+ * fragment, and neither changes which page it points at — and accepts a
+ * trailing slash on either side. This is the matcher `seo.internal-link-dead`
+ * uses, extracted so the inline field warning and the checks panel cannot
+ * disagree about what "dead" means.
+ */
+export declare function isKnownRoute(path: string, knownSlugs: Iterable<string>): boolean;
+/** A parsed link plus what the site knows about its target. */
+export type ResolvedLink = ParsedLink & {
+    /** The matching page, when `kind` is `page` and the route is known. */
+    page?: LinkPageOption;
+    /** True for a `page` link whose route matches nothing the site knows about. */
+    missing?: boolean;
+};
+/**
+ * Classify a link *and* look up its page. Pages may be keyed by `slug` or by
+ * `path` (they differ on locale-prefixed sites — see
+ * `docs/ideas/page-identity-punch-list.md`), so both are matched.
+ */
+export declare function resolveLink(value: unknown, pages?: readonly LinkPageOption[]): ResolvedLink;
+/**
+ * How well a page answers what was typed, from 0 (nothing in common) to 1.
+ *
+ * The balanced mean of precision and recall over shared words. Balanced because
+ * both halves are wrong alone: precision by itself ranks a sprawling page that
+ * happens to contain the word above the page actually named for it, and recall
+ * by itself ranks a one-word slug above every longer match.
+ *
+ * Pass the site's pages as `corpus` to weight words by how distinctive they are
+ * (see `tokenWeights`); without it every word counts the same.
+ */
+export declare function scoreLinkCandidate(query: string, page: LinkPageOption, corpus?: readonly LinkPageOption[]): number;
+/** Known pages ranked by how well they answer `query`, best first. */
+export declare function rankLinkTargets(query: string, pages: readonly LinkPageOption[]): LinkPageOption[];
+/**
+ * The page a dead internal link probably meant.
+ *
+ * `/avocado-sustainability` on a site that has `/sustainability` is a typo, a
+ * stale link, or a slug someone renamed by hand — and the site already holds
+ * everything needed to say so. Returns undefined when nothing scores well
+ * enough, or when the link already resolves; the caller offers what comes back,
+ * and never applies it on the editor's behalf.
+ */
+export declare function suggestLinkTarget(value: unknown, pages: readonly LinkPageOption[]): LinkPageOption | undefined;
+/**
+ * The absolute URL a viewer would copy out of the address bar, turned back into
+ * an internal route — when it belongs to this site.
+ *
+ * Pasting the address bar is how people actually get a URL, and an absolute one
+ * survives right up until the site moves domain. Returns undefined when the
+ * origin is someone else's, so the caller leaves the link alone.
+ */
+export declare function internalPathForUrl(value: string, siteOrigin: string | undefined): string | undefined;
+/**
+ * The prop holding the "open in new tab" flag for a link prop, by convention.
+ *
+ * `ctaHref` → `ctaNewTab`, `secondaryCtaHref` → `secondaryCtaNewTab`,
+ * `href` → `newTab`. The same shape as the `image`/`imageAlt` pairing the
+ * property panel already resolves by name, so a block declares two props and
+ * the editor renders one control.
+ */
+export declare function newTabKeyFor(linkKey: string): string;
+/** Anchor attributes for a link, given its stored value and new-tab flag. */
+export declare function linkAttrs(href: unknown, newTab?: unknown): {
+    href: string;
+    target?: string;
+    rel?: string;
+};

package/dist/links.js

@@ -0,0 +1,258 @@
+/**
+ * What a link field's string actually means.
+ *
+ * A link is stored as a plain string — `/pricing`, `https://example.com`,
+ * `mailto:hi@example.com` — and three places need to agree on how to read it:
+ * the editor's link control (which icon, which label, which warning), the
+ * `seo.internal-link-dead` check (is this route real?), and the rename rewriter
+ * (is this string a route at all?). Before this module each answered the
+ * question with its own inline `startsWith("/")`, and they did not agree: the
+ * rename rewriter matched on prop *names* containing "href", so a link stored
+ * under `url` or inside Footer's `label|url` text went stale on every rename.
+ *
+ * Nothing here validates in the blocking sense. A path this module cannot
+ * resolve is still a legitimate link — on a CMS-backed site Avocado sees only
+ * the pages it was handed, and a route can exist in Next, in the CMS, or behind
+ * a rewrite and be invisible from here. `resolveLink` reports what it knows; it
+ * never decides what the editor may type.
+ */
+/**
+ * A bare "/" is the default value every link field is born with
+ * (`defaultScalarForField`), so treating it as a real link to the homepage
+ * would make every freshly added card claim to link somewhere.
+ */
+function isEmptyValue(value) {
+    return value === "" || value === "/";
+}
+/** Classify a link string. Never throws; anything unrecognised parses as `page`-ish text. */
+export function parseLink(value) {
+    const raw = typeof value === "string" ? value : "";
+    const trimmed = raw.trim();
+    if (isEmptyValue(trimmed))
+        return { kind: "empty", raw };
+    if (/^mailto:/i.test(trimmed)) {
+        return { kind: "email", raw, target: trimmed.replace(/^mailto:/i, "") };
+    }
+    if (/^tel:/i.test(trimmed)) {
+        return { kind: "phone", raw, target: trimmed.replace(/^tel:/i, "") };
+    }
+    if (trimmed.startsWith("#")) {
+        return { kind: "anchor", raw, target: trimmed.slice(1) };
+    }
+    if (/^https?:\/\//i.test(trimmed)) {
+        let target = trimmed;
+        try {
+            const u = new URL(trimmed);
+            target = u.host + (u.pathname === "/" ? "" : u.pathname);
+        }
+        catch {
+            /* keep the raw string — a half-typed URL is still an external link */
+        }
+        return { kind: "external", raw, target };
+    }
+    /*
+     * A protocol-relative `//host/path` is external, not a route. Without this it
+     * would parse as a path and be reported dead against every site's slug list —
+     * and `draft-mode.ts` already rejects it for the same reason on the way in.
+     */
+    if (trimmed.startsWith("//"))
+        return { kind: "external", raw, target: trimmed.slice(2) };
+    /*
+     * Anything else is a route. Not only strings starting with "/": an editor who
+     * types "pricing" means the pricing page, and `normalizeLinkPath` is what
+     * turns that into one. Treating it as a page is also what lets the picker
+     * offer matches while you type.
+     */
+    const [pathPart = "", ...rest] = trimmed.split(/(?=[?#])/);
+    return { kind: "page", raw, path: pathPart, suffix: rest.join("") || undefined };
+}
+/**
+ * Give a route its leading slash and drop a trailing one.
+ *
+ * `pricing`, `/pricing`, `/pricing/` are the same page. The editor accepts all
+ * three and stores the middle one. The homepage keeps its lone slash.
+ */
+export function normalizeLinkPath(path) {
+    const trimmed = path.trim();
+    if (trimmed === "" || trimmed === "/")
+        return "/";
+    const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return withSlash.length > 1 ? withSlash.replace(/\/+$/, "") : withSlash;
+}
+/**
+ * Does this route exist among the site's known pages?
+ *
+ * Compares on the path alone — a link may legitimately carry a query or a
+ * fragment, and neither changes which page it points at — and accepts a
+ * trailing slash on either side. This is the matcher `seo.internal-link-dead`
+ * uses, extracted so the inline field warning and the checks panel cannot
+ * disagree about what "dead" means.
+ */
+export function isKnownRoute(path, knownSlugs) {
+    const known = knownSlugs instanceof Set ? knownSlugs : new Set(knownSlugs);
+    const target = path.split(/[?#]/)[0] ?? "";
+    const normalized = normalizeLinkPath(target);
+    return known.has(target) || known.has(normalized) || known.has(`${normalized}/`);
+}
+/**
+ * Classify a link *and* look up its page. Pages may be keyed by `slug` or by
+ * `path` (they differ on locale-prefixed sites — see
+ * `docs/ideas/page-identity-punch-list.md`), so both are matched.
+ */
+export function resolveLink(value, pages = []) {
+    const parsed = parseLink(value);
+    if (parsed.kind !== "page")
+        return parsed;
+    const wanted = normalizeLinkPath(parsed.path ?? "");
+    const page = pages.find((p) => normalizeLinkPath(p.slug) === wanted || (p.path != null && normalizeLinkPath(p.path) === wanted));
+    if (page)
+        return { ...parsed, page };
+    return { ...parsed, missing: true };
+}
+// ---------------------------------------------------------------------------
+// Suggesting a page
+// ---------------------------------------------------------------------------
+/** Words in a slug, a path or a title, lowercased and punctuation-free. */
+function tokenize(value) {
+    return value.toLowerCase().split(/[^a-z0-9]+/i).filter((t) => t.length > 0);
+}
+/** Everything a page can be recognised by: its slug, its URL and its title. */
+function pageTokens(page) {
+    return [...new Set([...tokenize(page.slug), ...tokenize(page.path ?? ""), ...tokenize(page.title ?? "")])];
+}
+/**
+ * How much each word says about *which* page is meant.
+ *
+ * A word every page carries — a locale prefix, the company name — identifies
+ * nothing, and counting it equally is what makes a naive matcher propose
+ * `/de/impressum` for `/de/veranstaltungen`: the two share only the "de". This
+ * is inverse document frequency over the site's own pages, smoothed so a word
+ * on no page at all still has a finite weight.
+ */
+function tokenWeights(pages) {
+    const total = pages.length;
+    const seen = new Map();
+    for (const page of pages) {
+        for (const token of pageTokens(page))
+            seen.set(token, (seen.get(token) ?? 0) + 1);
+    }
+    const weights = new Map();
+    for (const [token, count] of seen)
+        weights.set(token, Math.log(1 + total / (count + 1)));
+    return weights;
+}
+function weightOf(token, weights, total) {
+    if (!weights)
+        return 1;
+    return weights.get(token) ?? Math.log(1 + total);
+}
+/**
+ * How well a page answers what was typed, from 0 (nothing in common) to 1.
+ *
+ * The balanced mean of precision and recall over shared words. Balanced because
+ * both halves are wrong alone: precision by itself ranks a sprawling page that
+ * happens to contain the word above the page actually named for it, and recall
+ * by itself ranks a one-word slug above every longer match.
+ *
+ * Pass the site's pages as `corpus` to weight words by how distinctive they are
+ * (see `tokenWeights`); without it every word counts the same.
+ */
+export function scoreLinkCandidate(query, page, corpus) {
+    const wanted = [...new Set(tokenize(query))];
+    if (wanted.length === 0)
+        return 0;
+    const have = pageTokens(page);
+    if (have.length === 0)
+        return 0;
+    const weights = corpus ? tokenWeights(corpus) : undefined;
+    const total = corpus?.length ?? 0;
+    const w = (token) => weightOf(token, weights, total);
+    const sum = (tokens) => tokens.reduce((acc, t) => acc + w(t), 0);
+    const shared = wanted.filter((t) => have.includes(t));
+    if (shared.length === 0)
+        return 0;
+    const overlap = sum(shared);
+    const precision = overlap / sum(wanted);
+    const recall = overlap / sum(have);
+    return (2 * precision * recall) / (precision + recall);
+}
+/**
+ * Below this a "did you mean" is noise, and a wrong suggestion is worse than
+ * none — the editor has to stop and rule it out.
+ */
+const SUGGESTION_MIN_SCORE = 0.45;
+/** Known pages ranked by how well they answer `query`, best first. */
+export function rankLinkTargets(query, pages) {
+    return pages
+        .map((page) => ({ page, score: scoreLinkCandidate(query, page, pages) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .map((entry) => entry.page);
+}
+/**
+ * The page a dead internal link probably meant.
+ *
+ * `/avocado-sustainability` on a site that has `/sustainability` is a typo, a
+ * stale link, or a slug someone renamed by hand — and the site already holds
+ * everything needed to say so. Returns undefined when nothing scores well
+ * enough, or when the link already resolves; the caller offers what comes back,
+ * and never applies it on the editor's behalf.
+ */
+export function suggestLinkTarget(value, pages) {
+    const resolved = resolveLink(value, pages);
+    if (resolved.kind !== "page" || !resolved.missing)
+        return undefined;
+    const best = pages
+        .map((page) => ({ page, score: scoreLinkCandidate(resolved.path ?? "", page, pages) }))
+        .sort((a, b) => b.score - a.score)[0];
+    return best && best.score >= SUGGESTION_MIN_SCORE ? best.page : undefined;
+}
+/**
+ * The absolute URL a viewer would copy out of the address bar, turned back into
+ * an internal route — when it belongs to this site.
+ *
+ * Pasting the address bar is how people actually get a URL, and an absolute one
+ * survives right up until the site moves domain. Returns undefined when the
+ * origin is someone else's, so the caller leaves the link alone.
+ */
+export function internalPathForUrl(value, siteOrigin) {
+    if (!siteOrigin)
+        return undefined;
+    let url;
+    let origin;
+    try {
+        url = new URL(value);
+        origin = new URL(siteOrigin);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.host !== origin.host)
+        return undefined;
+    return normalizeLinkPath(url.pathname) + url.search + url.hash;
+}
+/**
+ * The prop holding the "open in new tab" flag for a link prop, by convention.
+ *
+ * `ctaHref` → `ctaNewTab`, `secondaryCtaHref` → `secondaryCtaNewTab`,
+ * `href` → `newTab`. The same shape as the `image`/`imageAlt` pairing the
+ * property panel already resolves by name, so a block declares two props and
+ * the editor renders one control.
+ */
+export function newTabKeyFor(linkKey) {
+    const base = linkKey.replace(/href$/i, "");
+    return base ? `${base}NewTab` : "newTab";
+}
+/** Anchor attributes for a link, given its stored value and new-tab flag. */
+export function linkAttrs(href, newTab) {
+    const value = typeof href === "string" && href.length > 0 ? href : "#";
+    /*
+     * `noopener` is not decoration. A `_blank` link without it hands the opened
+     * page a live `window.opener` handle on this one, which is a real
+     * cross-origin hazard and the reason the pair always ships together.
+     */
+    if (newTab === true && parseLink(value).kind === "external") {
+        return { href: value, target: "_blank", rel: "noopener noreferrer" };
+    }
+    return { href: value };
+}

package/package.json

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