canopycms 0.0.62 → 0.0.63

package/dist/static/seo.js

@@ -0,0 +1,189 @@
+/**
+ * Framework-agnostic SEO field extraction and URL shaping.
+ *
+ * This module is pure: it maps an entry's raw data onto a neutral `SeoFields` shape and
+ * resolves URLs. Framework adapters (e.g. canopycms-next's `entryToMetadata`) turn that shape
+ * into their own metadata objects; nothing here imports a framework or a node built-in.
+ *
+ * The field names default to the recommended SEO field group — see `defineSeoFieldGroup` in
+ * entry-schema.ts, which builds a schema group from these same names so the schema side and
+ * the read side cannot drift.
+ */
+import { neutralizeImplicitOffOrigin } from '../utils/sanitize-href.js';
+/**
+ * The recommended SEO field names. `defineSeoFieldGroup()` emits a schema group using exactly
+ * these names, so an adopter who uses both ends needs no configuration at all.
+ */
+export const DEFAULT_SEO_FIELD_NAMES = {
+    title: 'metaTitle',
+    description: 'metaDescription',
+    ogImage: 'ogImage',
+    ogType: 'ogType',
+    canonical: 'canonical',
+    noindex: 'noindex',
+    twitterCard: 'twitterCard',
+};
+const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * A non-empty trimmed string, or undefined.
+ *
+ * Empty is treated as UNSET, deliberately: CanopyCMS writes optional fields present-but-empty
+ * rather than omitting them, so `metaTitle: ''` is what an untouched SEO group looks like on
+ * disk. Treating it as a value would let a blank field beat the fallback title on every entry
+ * whose author never opened the SEO section.
+ */
+const asText = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+};
+const asFlag = (value) => typeof value === 'boolean' ? value : undefined;
+/**
+ * An image URL from either convention: a plain string field, or an `image` field, whose value
+ * is a structured `{ src, alt, ... }` object. Supporting both means switching the recommended
+ * `ogImage` field to `type: 'image'` doesn't silently drop every OG image.
+ */
+const asImageUrl = (value) => {
+    const text = asText(value);
+    if (text)
+        return text;
+    return asText(asRecord(value)?.src);
+};
+const asOgType = (value) => {
+    const text = asText(value);
+    return text === 'website' || text === 'article' || text === 'profile' ? text : undefined;
+};
+const asTwitterCard = (value) => {
+    const text = asText(value);
+    return text === 'summary' || text === 'summary_large_image' ? text : undefined;
+};
+/**
+ * Map an entry's SEO fields onto the neutral shape.
+ *
+ * Entry data is `unknown` — every read is guarded, unknown enum values are dropped rather than
+ * passed through, and non-object data (null, a string, an array) yields an all-undefined result
+ * rather than throwing.
+ */
+export function extractSeoFields(entryData, opts = {}) {
+    const names = { ...DEFAULT_SEO_FIELD_NAMES, ...opts.fields };
+    const entry = asRecord(entryData);
+    const source = opts.group ? asRecord(entry?.[opts.group]) : entry;
+    return {
+        title: asText(source?.[names.title]) ?? asText(opts.fallbackTitle),
+        description: asText(source?.[names.description]) ?? asText(opts.fallbackDescription),
+        ogImage: asImageUrl(source?.[names.ogImage]),
+        ogType: asOgType(source?.[names.ogType]),
+        canonical: asText(source?.[names.canonical]),
+        noindex: asFlag(source?.[names.noindex]),
+        twitterCard: asTwitterCard(source?.[names.twitterCard]),
+    };
+}
+/**
+ * THE `noindex` predicate. Every surface that suppresses an entry must route through this one
+ * function rather than re-deriving the flag:
+ *
+ * - the page's own `robots: { index: false }` (canopycms-next's `entryToMetadata`), and
+ * - exclusion from the sitemap (canopycms-next's `generateContentSitemap`).
+ *
+ * Those two shipping from one predicate is the point of shipping them together. Where they were
+ * derived separately, a `noindex` entry stayed advertised in one surface while correctly absent
+ * from the other, and nothing warned.
+ *
+ * NOT applied to enumeration: `noindex` means "don't advertise this", not "don't build this".
+ * `collectRoutableEntries` and `generateStaticParams` must still emit the entry, so its URL
+ * resolves for anyone holding the link.
+ */
+export function isNoindexEntry(entryData, opts = {}) {
+    return extractSeoFields(entryData, opts).noindex === true;
+}
+/**
+ * An off-site URL: either scheme-qualified (`https://…`) or LITERAL protocol-relative
+ * (`//cdn…`). Both name a host we don't control, so neither may be rewritten against the site
+ * origin — `resolveSeoUrl` passes a `true` result through verbatim.
+ *
+ * Deliberately narrower than "resolves off-origin": a WHATWG-backslash-equivalent spelling
+ * (`/\evil.com`, `\\evil.com`, `\/evil.com` — see `utils/sanitize-href.ts`'s
+ * `isImplicitlyOffOrigin`) also resolves off-origin in a browser, but is NOT recognized here as
+ * an intentional off-site pointer the way a literal `//cdn…` is. `resolveSeoUrl` handles that
+ * case separately, by neutralizing (`neutralizeImplicitOffOrigin`) rather than passing through: a
+ * `false` result here isn't a guarantee the value is a safe site-relative path on its own, only
+ * that it isn't a *declared* off-site one.
+ */
+export function isAbsoluteUrl(url) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('//');
+}
+/**
+ * Strip trailing slashes without a regex.
+ *
+ * The obvious `replace(/\/+$/, '')` is a polynomial-ReDoS shape (CodeQL
+ * `js/polynomial-redos`, flagged high): on a value that is mostly slashes but does not end in
+ * one, the engine retries `\/+` from every position and the match cost is quadratic in the
+ * input length. `siteUrl` is adopter-supplied and can reach here from config or an env var, so
+ * it counts as uncontrolled. A character scan is linear and needs no reasoning about
+ * backtracking.
+ *
+ * Exported (from `canopycms/server`) so adopter code normalizing its own site-origin env var —
+ * e.g. a `SITE_URL` constant built from `NEXT_PUBLIC_SITE_URL` — has a package-provided linear
+ * way to do it instead of reaching for the same regex this function replaced.
+ */
+export function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */)
+        end--;
+    return value.slice(0, end);
+}
+/**
+ * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
+ *
+ * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
+ * `/blog/rss.xml`) alone, and never doubles an existing slash.
+ *
+ * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
+ * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
+ * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
+ * with a trailing slash" means and breaks the URL).
+ */
+export function withTrailingSlash(path) {
+    const splitIndex = path.search(/[?#]/);
+    const base = splitIndex === -1 ? path : path.slice(0, splitIndex);
+    const suffix = splitIndex === -1 ? '' : path.slice(splitIndex);
+    const withLeading = base.startsWith('/') ? base : `/${base}`;
+    if (withLeading === '/' || withLeading.endsWith('/'))
+        return withLeading + suffix;
+    const lastSegment = withLeading.slice(withLeading.lastIndexOf('/') + 1);
+    if (lastSegment.includes('.'))
+        return withLeading + suffix;
+    return `${withLeading}/${suffix}`;
+}
+/**
+ * Resolve a possibly-relative URL for public emission (canonical tag, sitemap URL, OG image).
+ *
+ * ORDER MATTERS — the absolute check runs FIRST. An absolute or protocol-relative value is a
+ * deliberate off-site pointer (syndication, a partner-hosted copy, a CDN image) and passes
+ * through verbatim; only a site-relative path gets trailing-slash normalization and the site
+ * origin. Normalizing first turns `https://other.org/page` into
+ * `<siteUrl>/https://other.org/page/`.
+ *
+ * With no `siteUrl`, a site-relative path is returned still relative (normalized), which is
+ * what you want when the framework resolves relative metadata URLs itself.
+ *
+ * A NOT-absolute value is also run through `neutralizeImplicitOffOrigin` before normalization,
+ * so a WHATWG-backslash-equivalent spelling that `isAbsoluteUrl` correctly declines to call
+ * "absolute" (see its doc) can't still be read by a browser as protocol-relative once emitted.
+ */
+export function resolveSeoUrl(pathOrUrl, opts = {}) {
+    if (isAbsoluteUrl(pathOrUrl))
+        return pathOrUrl;
+    const safePathOrUrl = neutralizeImplicitOffOrigin(pathOrUrl);
+    const normalized = opts.trailingSlash
+        ? withTrailingSlash(safePathOrUrl)
+        : safePathOrUrl.startsWith('/')
+            ? safePathOrUrl
+            : `/${safePathOrUrl}`;
+    const origin = opts.siteUrl === undefined ? undefined : stripTrailingSlashes(opts.siteUrl);
+    return origin ? origin + normalized : normalized;
+}
+//# sourceMappingURL=seo.js.map

package/dist/static/seo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.js","sourceRoot":"","sources":["../../src/static/seo.ts"],"names":[],"mappings":"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"}

package/dist/utils/sanitize-href.d.ts

@@ -1,3 +1,49 @@
+/**
+ * Whether `url` declares an explicit scheme (`https:`, `mailto:`, `javascript:`, ...).
+ *
+ * This is the property that actually distinguishes "the author asked for another origin" from
+ * "the parser inferred one" -- see `sanitizeHref`'s doc for why a `startsWith('//')` /
+ * `startsWith('scheme://')` check is not sufficient on its own (WHATWG URL treats backslash as
+ * equivalent to forward slash for special schemes, so `/\evil.com`, `\\evil.com` and `\/evil.com`
+ * are all protocol-relative in effect despite declaring no scheme). Exported so every "is this
+ * URL off-site" check in the package shares one answer instead of re-deriving it -- see
+ * `isImplicitlyOffOrigin` below and `static/seo.ts`'s `isAbsoluteUrl`.
+ */
+export declare function declaresScheme(url: string): boolean;
+/**
+ * Whether `url`, resolved as a URL reference against a fixed sentinel origin, lands on a
+ * DIFFERENT origin than the sentinel WITHOUT itself declaring a scheme.
+ *
+ * True for a literal protocol-relative reference (`//host`) and for every WHATWG
+ * backslash-equivalent spelling that a browser resolves the same way (`/\host`, `\\host`,
+ * `\/host`, and combinations with stripped whitespace/control characters) -- these all read as
+ * "site-relative" to a naive string check but actually redefine the authority. False for a
+ * normal site-relative path (`/about`, `docs/guide`) and for a scheme-qualified absolute URL
+ * (`declaresScheme` already identifies those as intentionally off-site on their own).
+ *
+ * Callers that want to treat a LITERAL `//host` as an intentionally-supported off-site pointer
+ * (e.g. `static/seo.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
+ * separately and only fall back to this function to catch the spellings that slip past a
+ * `startsWith('//')` check.
+ */
+export declare function isImplicitlyOffOrigin(url: string): boolean;
+/**
+ * If `url` `isImplicitlyOffOrigin`, discard the authority it spoofed and return just the
+ * path/search/hash it resolved to -- e.g. `/\evil.com/x` (which parses to origin
+ * `https://evil.com`) becomes `/x`. Otherwise return `url` unchanged.
+ *
+ * This re-parses with the SAME sentinel technique rather than pattern-matching leading
+ * slash/backslash characters: WHATWG URL also strips tabs, newlines, and carriage returns during
+ * parsing (wherever they appear, not just at the edges), so `/\t/evil.com` is exactly as
+ * off-origin as `/\evil.com` despite having no leading backslash-or-slash run for a regex to
+ * find. Re-parsing gets this right for free instead of re-deriving the quirk a second time.
+ *
+ * Useful for a caller that wants to keep emitting SOME value for an implicitly-off-origin input
+ * rather than rejecting it outright (`sanitizeHref` rejects to a fallback instead; see
+ * `static/seo.ts`'s `resolveSeoUrl`, which has no fallback concept and must always return a
+ * same-origin string).
+ */
+export declare function neutralizeImplicitOffOrigin(url: string): string;
 /**
  * Sanitize an untrusted URL for use in `href` attributes.
  *

package/dist/utils/sanitize-href.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize-href.d.ts","sourceRoot":"","sources":["../../src/utils/sanitize-href.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,MAAM,CAyChE"}
+{"version":3,"file":"sanitize-href.d.ts","sourceRoot":"","sources":["../../src/utils/sanitize-href.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,MAAM,CAwChE"}

package/dist/utils/sanitize-href.js

@@ -2,6 +2,68 @@
 // fragment-only, query-only) resolve instead of throwing under `new URL()`.
 // Never exposed in output - see the relative-reference branch below.
 const SENTINEL_BASE = 'https://relative.invalid';
+/**
+ * Whether `url` declares an explicit scheme (`https:`, `mailto:`, `javascript:`, ...).
+ *
+ * This is the property that actually distinguishes "the author asked for another origin" from
+ * "the parser inferred one" -- see `sanitizeHref`'s doc for why a `startsWith('//')` /
+ * `startsWith('scheme://')` check is not sufficient on its own (WHATWG URL treats backslash as
+ * equivalent to forward slash for special schemes, so `/\evil.com`, `\\evil.com` and `\/evil.com`
+ * are all protocol-relative in effect despite declaring no scheme). Exported so every "is this
+ * URL off-site" check in the package shares one answer instead of re-deriving it -- see
+ * `isImplicitlyOffOrigin` below and `static/seo.ts`'s `isAbsoluteUrl`.
+ */
+export function declaresScheme(url) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(url.trim());
+}
+/**
+ * Whether `url`, resolved as a URL reference against a fixed sentinel origin, lands on a
+ * DIFFERENT origin than the sentinel WITHOUT itself declaring a scheme.
+ *
+ * True for a literal protocol-relative reference (`//host`) and for every WHATWG
+ * backslash-equivalent spelling that a browser resolves the same way (`/\host`, `\\host`,
+ * `\/host`, and combinations with stripped whitespace/control characters) -- these all read as
+ * "site-relative" to a naive string check but actually redefine the authority. False for a
+ * normal site-relative path (`/about`, `docs/guide`) and for a scheme-qualified absolute URL
+ * (`declaresScheme` already identifies those as intentionally off-site on their own).
+ *
+ * Callers that want to treat a LITERAL `//host` as an intentionally-supported off-site pointer
+ * (e.g. `static/seo.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
+ * separately and only fall back to this function to catch the spellings that slip past a
+ * `startsWith('//')` check.
+ */
+export function isImplicitlyOffOrigin(url) {
+    if (declaresScheme(url))
+        return false;
+    try {
+        return new URL(url, SENTINEL_BASE).origin !== SENTINEL_BASE;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * If `url` `isImplicitlyOffOrigin`, discard the authority it spoofed and return just the
+ * path/search/hash it resolved to -- e.g. `/\evil.com/x` (which parses to origin
+ * `https://evil.com`) becomes `/x`. Otherwise return `url` unchanged.
+ *
+ * This re-parses with the SAME sentinel technique rather than pattern-matching leading
+ * slash/backslash characters: WHATWG URL also strips tabs, newlines, and carriage returns during
+ * parsing (wherever they appear, not just at the edges), so `/\t/evil.com` is exactly as
+ * off-origin as `/\evil.com` despite having no leading backslash-or-slash run for a regex to
+ * find. Re-parsing gets this right for free instead of re-deriving the quirk a second time.
+ *
+ * Useful for a caller that wants to keep emitting SOME value for an implicitly-off-origin input
+ * rather than rejecting it outright (`sanitizeHref` rejects to a fallback instead; see
+ * `static/seo.ts`'s `resolveSeoUrl`, which has no fallback concept and must always return a
+ * same-origin string).
+ */
+export function neutralizeImplicitOffOrigin(url) {
+    if (!isImplicitlyOffOrigin(url))
+        return url;
+    const parsed = new URL(url, SENTINEL_BASE);
+    return parsed.pathname + parsed.search + parsed.hash;
+}
 /**
  * Sanitize an untrusted URL for use in `href` attributes.
  *
@@ -67,8 +129,7 @@ export function sanitizeHref(url, fallback = '#') {
         // origin" from "the parser inferred one" is whether the input DECLARES a
         // scheme. If it does not and still resolved off the sentinel, it is
         // protocol-relative however it was written.
-        const declaresScheme = /^[a-z][a-z0-9+.-]*:/i.test(trimmed);
-        if (parsed.origin !== SENTINEL_BASE && !declaresScheme)
+        if (parsed.origin !== SENTINEL_BASE && !declaresScheme(trimmed))
             return fallback;
         if (parsed.origin === SENTINEL_BASE) {
             // Input was relative: return it as a relative reference rather than

package/dist/utils/sanitize-href.js.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize-href.js","sourceRoot":"","sources":["../../src/utils/sanitize-href.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,4EAA4E;AAC5E,qEAAqE;AACrE,MAAM,aAAa,GAAG,0BAA0B,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,QAAQ,GAAG,GAAG;IACtD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;IAC1B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAA;IAEnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;QAC9C,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAChE,OAAO,QAAQ,CAAA;QACjB,CAAC;QAED,wEAAwE;QACxE,qEAAqE;QACrE,EAAE;QACF,uEAAuE;QACvE,qEAAqE;QACrE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,yEAAyE;QACzE,EAAE;QACF,yEAAyE;QACzE,yEAAyE;QACzE,oEAAoE;QACpE,4CAA4C;QAC5C,MAAM,cAAc,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAC3D,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,IAAI,CAAC,cAAc;YAAE,OAAO,QAAQ,CAAA;QAEvE,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;YACpC,oEAAoE;YACpE,kDAAkD;YAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAA;YAC9D,mEAAmE;YACnE,kEAAkE;YAClE,OAAO,MAAM,CAAC,QAAQ,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;QAC3F,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAA;IACpB,CAAC;IAAC,MAAM,CAAC;QACP,cAAc;IAChB,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}
+{"version":3,"file":"sanitize-href.js","sourceRoot":"","sources":["../../src/utils/sanitize-href.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,4EAA4E;AAC5E,qEAAqE;AACrE,MAAM,aAAa,GAAG,0BAA0B,CAAA;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;AAChD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,IAAI,cAAc,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAA;IACrC,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,MAAM,KAAK,aAAa,CAAA;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAW;IACrD,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAA;IAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,CAAA;IAC1C,OAAO,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAA;AACtD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,QAAQ,GAAG,GAAG;IACtD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;IAC1B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAA;IAEnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;QAC9C,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAChE,OAAO,QAAQ,CAAA;QACjB,CAAC;QAED,wEAAwE;QACxE,qEAAqE;QACrE,EAAE;QACF,uEAAuE;QACvE,qEAAqE;QACrE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,yEAAyE;QACzE,EAAE;QACF,yEAAyE;QACzE,yEAAyE;QACzE,oEAAoE;QACpE,4CAA4C;QAC5C,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC;YAAE,OAAO,QAAQ,CAAA;QAEhF,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;YACpC,oEAAoE;YACpE,kDAAkD;YAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAA;YAC9D,mEAAmE;YACnE,kEAAkE;YAClE,OAAO,MAAM,CAAC,QAAQ,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;QAC3F,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAA;IACpB,CAAC;IAAC,MAAM,CAAC;QACP,cAAc;IAChB,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@codemirror/language, @lezer/highlight: workaround — @mdxeditor/editor uses cm6-theme-basic-light which peer-requires these but mdxeditor doesn't declare them as dependencies",
   "name": "canopycms",
-  "version": "0.0.62",
+  "version": "0.0.63",
   "description": "CanopyCMS core package: schema-driven content, branch-aware editing, and editor UI for Next.js.",
   "license": "MIT",
   "repository": {