@velastack/cms 0.5.0 → 0.6.0

package/dist/core/structured.d.ts

@@ -31,18 +31,28 @@ export type TranslationOverlay = Record<string, Record<string, string>>;
 export type StructuredItem = {
     id: string;
 } & Record<string, unknown>;
+/**
+ * One list of items inside a structured value. `key` names the array field,
+ * `translatable` the item fields holding translatable text (a string, or an
+ * array of strings, translated per index as `<field>.<i>`), and `items` any
+ * lists nested inside each item (a collection item's `details`, a pricing
+ * tier's `features`). Every item at every level carries a stable `id`.
+ */
+export type ItemsSpec = {
+    key: string;
+    translatable: readonly string[];
+    items?: ItemsSpec | readonly ItemsSpec[];
+};
 export type StructuredSchema<T extends Tree> = {
     /** Exported component name, e.g. `'CmsHours'`. Recorded in the manifest. */
     component: string;
     /** Current shape version, written as `v` on every value. */
     version: number;
-    /** Root-level fields holding translatable strings, e.g. `['note']`. */
+    /** Root-level fields holding translatable strings, e.g. `['note']`. A
+     * dotted path addresses a nested field (`'labels.closed'`). */
     translatable: readonly string[];
-    /** The item list, when the value has one, and the item fields that translate. */
-    items?: {
-        key: string;
-        translatable: readonly string[];
-    };
+    /** The value's item lists, when it has any, and the item fields that translate. */
+    items?: ItemsSpec | readonly ItemsSpec[];
     /**
      * Turn anything the store may hold — an older version, a hand-seeded
      * partial object, garbage — into the current shape. Must never throw.
@@ -63,21 +73,26 @@ export declare const isPlainObject: (v: unknown) => v is Tree;
 export declare const defineStructured: <T extends Tree>(schema: StructuredSchema<T>) => Structured<T>;
 /** Path of one translated string: `<name>.$t.<id>.<field>`. */
 export declare const translationPath: (name: string, id: string, field: string) => string;
-/** The `$t` branch of a stored value, when it is one. */
+/** The `$t` branch of a stored value, when it is one. A dotted field
+ * (`labels.closed`, `tags.0`) is stored nested by the path-based writes and
+ * read back flat here. */
 export declare const extractTranslations: (raw: unknown) => TranslationOverlay | undefined;
 /** A copy of `raw` without its `$t` branch, so a whole-object write in the
  * default locale never carries another locale's strings. */
 export declare const stripTranslations: (raw: unknown) => unknown;
+/** `set` that copies along the path instead of mutating shared branches. */
+export declare const setIn: (obj: Tree, path: string, value: unknown) => Tree;
 /**
  * Fold a locale's string overlay into a normalized default-locale value.
- * Root fields come from the `_` id; item fields from the item's own `id`.
- * Only non-empty strings override, so an untranslated field shows the
- * default-locale text rather than a blank.
+ * Root fields come from the `_` id; item fields from the item's own `id`,
+ * at every nesting level. Only non-empty strings override, so an
+ * untranslated field shows the default-locale text rather than a blank.
  */
 export declare const applyTranslations: <T extends Tree>(value: T, overlay: TranslationOverlay | undefined, schema: Pick<StructuredSchema<T>, "translatable" | "items">) => T;
 export type TranslatableField = {
     /** Overlay id: an item id, or `_` for a root field. */
     id: string;
+    /** Field path within the object the id addresses (`note`, `labels.closed`, `tags.0`). */
     field: string;
     /** The default-locale string being translated. */
     source: string;
@@ -106,3 +121,11 @@ export declare const asItems: <I extends StructuredItem>(raw: unknown, normalize
 export declare const newItemId: () => string;
 /** Read a structured value's overlay for one locale out of a whole scope tree. */
 export declare const overlayAt: (tree: Tree | undefined, name: string) => TranslationOverlay | undefined;
+/** A list of strings; anything else is dropped. */
+export declare const asStrings: (v: unknown) => string[];
+/** A nullable string: `null` (cleared) stays `null`; anything else is a string. */
+export declare const asOptionalString: (v: unknown) => string | null;
+/** One of a fixed set of strings, else the fallback. */
+export declare const asEnum: <E extends string>(v: unknown, values: readonly E[], fallback: E) => E;
+/** Move an item within a list, returning a new list. */
+export declare const moveItem: <I>(list: readonly I[], from: number, to: number) => I[];

package/dist/core/structured.js

@@ -21,7 +21,7 @@
  *    the default locale only, so the item list can never fork between
  *    languages.
  */
-import { get } from './path.js';
+import { get, leafPaths } from './path.js';
 /** Branch under a structured value that holds a locale's string overlay. */
 export const TRANSLATIONS_KEY = '$t';
 /** Overlay id that addresses the structured value's root fields. */
@@ -31,7 +31,7 @@ export const defineStructured = (schema) => ({
     ...schema,
     read: (raw, fallback) => {
         if (raw === undefined)
-            return fallback === undefined ? schema.empty() : fallback;
+            return fallback === undefined ? schema.empty() : schema.normalize(fallback);
         if (raw === null)
             return schema.empty();
         const overlay = extractTranslations(raw);
@@ -41,7 +41,9 @@ export const defineStructured = (schema) => ({
 });
 /** Path of one translated string: `<name>.$t.<id>.<field>`. */
 export const translationPath = (name, id, field) => `${name}.${TRANSLATIONS_KEY}.${id}.${field}`;
-/** The `$t` branch of a stored value, when it is one. */
+/** The `$t` branch of a stored value, when it is one. A dotted field
+ * (`labels.closed`, `tags.0`) is stored nested by the path-based writes and
+ * read back flat here. */
 export const extractTranslations = (raw) => {
     if (!isPlainObject(raw))
         return undefined;
@@ -53,9 +55,10 @@ export const extractTranslations = (raw) => {
         if (!isPlainObject(fields))
             continue;
         const strings = {};
-        for (const [field, v] of Object.entries(fields)) {
+        for (const path of leafPaths(fields)) {
+            const v = get(fields, path);
             if (typeof v === 'string')
-                strings[field] = v;
+                strings[path] = v;
         }
         out[id] = strings;
     }
@@ -73,38 +76,91 @@ const overlayString = (overlay, id, field) => {
     const v = overlay[id]?.[field];
     return typeof v === 'string' && v !== '' ? v : undefined;
 };
+const specList = (items) => items === undefined ? [] : Array.isArray(items) ? items : [items];
+const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+/** `set` that copies along the path instead of mutating shared branches. */
+export const setIn = (obj, path, value) => {
+    const [head, ...rest] = path.split('.');
+    const out = { ...obj };
+    if (rest.length === 0) {
+        out[head] = value;
+        return out;
+    }
+    const child = obj[head];
+    out[head] = setIn(isPlainObject(child) ? child : {}, rest.join('.'), value);
+    return out;
+};
+/**
+ * Fold a locale's string overlay into one object (the root value or an item)
+ * and, recursively, into the item lists it holds.
+ */
+const applyTo = (obj, id, translatable, items, overlay) => {
+    let out = { ...obj };
+    for (const field of translatable) {
+        const cur = get(obj, field);
+        if (typeof cur === 'string') {
+            const s = overlayString(overlay, id, field);
+            if (s !== undefined)
+                out = setIn(out, field, s);
+        }
+        else if (isStringArray(cur)) {
+            let changed = false;
+            const next = cur.map((v, i) => {
+                const s = overlayString(overlay, id, `${field}.${i}`);
+                if (s === undefined)
+                    return v;
+                changed = true;
+                return s;
+            });
+            if (changed)
+                out = setIn(out, field, next);
+        }
+    }
+    for (const spec of specList(items)) {
+        const list = obj[spec.key];
+        if (!Array.isArray(list))
+            continue;
+        out[spec.key] = list.map((item) => isPlainObject(item) && typeof item.id === 'string'
+            ? applyTo(item, item.id, spec.translatable, spec.items, overlay)
+            : item);
+    }
+    return out;
+};
 /**
  * Fold a locale's string overlay into a normalized default-locale value.
- * Root fields come from the `_` id; item fields from the item's own `id`.
- * Only non-empty strings override, so an untranslated field shows the
- * default-locale text rather than a blank.
+ * Root fields come from the `_` id; item fields from the item's own `id`,
+ * at every nesting level. Only non-empty strings override, so an
+ * untranslated field shows the default-locale text rather than a blank.
  */
 export const applyTranslations = (value, overlay, schema) => {
     if (!overlay)
         return value;
-    const out = { ...value };
-    for (const field of schema.translatable) {
-        const s = overlayString(overlay, ROOT_ID, field);
-        if (s !== undefined)
-            out[field] = s;
-    }
-    if (schema.items) {
-        const list = value[schema.items.key];
-        if (Array.isArray(list)) {
-            out[schema.items.key] = list.map((item) => {
-                if (!isPlainObject(item) || typeof item.id !== 'string')
-                    return item;
-                const next = { ...item };
-                for (const field of schema.items.translatable) {
-                    const s = overlayString(overlay, item.id, field);
-                    if (s !== undefined)
-                        next[field] = s;
-                }
-                return next;
+    return applyTo(value, ROOT_ID, schema.translatable, schema.items, overlay);
+};
+const collectFrom = (obj, id, translatable, items, out) => {
+    for (const field of translatable) {
+        const cur = get(obj, field);
+        if (typeof cur === 'string') {
+            if (cur !== '')
+                out.push({ id, field, source: cur });
+        }
+        else if (isStringArray(cur)) {
+            cur.forEach((s, i) => {
+                if (s !== '')
+                    out.push({ id, field: `${field}.${i}`, source: s });
             });
         }
     }
-    return out;
+    for (const spec of specList(items)) {
+        const list = obj[spec.key];
+        if (!Array.isArray(list))
+            continue;
+        for (const item of list) {
+            if (!isPlainObject(item) || typeof item.id !== 'string')
+                continue;
+            collectFrom(item, item.id, spec.translatable, spec.items, out);
+        }
+    }
 };
 /**
  * Every translatable, non-empty string in a normalized default-locale value.
@@ -112,25 +168,7 @@ export const applyTranslations = (value, overlay, schema) => {
  */
 export const translatableFields = (value, schema) => {
     const out = [];
-    for (const field of schema.translatable) {
-        const s = value[field];
-        if (typeof s === 'string' && s !== '')
-            out.push({ id: ROOT_ID, field, source: s });
-    }
-    if (schema.items) {
-        const list = value[schema.items.key];
-        if (Array.isArray(list)) {
-            for (const item of list) {
-                if (!isPlainObject(item) || typeof item.id !== 'string')
-                    continue;
-                for (const field of schema.items.translatable) {
-                    const s = item[field];
-                    if (typeof s === 'string' && s !== '')
-                        out.push({ id: item.id, field, source: s });
-                }
-            }
-        }
-    }
+    collectFrom(value, ROOT_ID, schema.translatable, schema.items, out);
     return out;
 };
 /** How many translatable strings a locale's overlay still lacks. */
@@ -182,3 +220,16 @@ export const newItemId = () => {
 };
 /** Read a structured value's overlay for one locale out of a whole scope tree. */
 export const overlayAt = (tree, name) => extractTranslations(get(tree, name));
+/** A list of strings; anything else is dropped. */
+export const asStrings = (v) => Array.isArray(v) ? v.filter((s) => typeof s === 'string') : [];
+/** A nullable string: `null` (cleared) stays `null`; anything else is a string. */
+export const asOptionalString = (v) => typeof v === 'string' && v !== '' ? v : null;
+/** One of a fixed set of strings, else the fallback. */
+export const asEnum = (v, values, fallback) => typeof v === 'string' && values.includes(v) ? v : fallback;
+/** Move an item within a list, returning a new list. */
+export const moveItem = (list, from, to) => {
+    const next = [...list];
+    const [item] = next.splice(from, 1);
+    next.splice(to, 0, item);
+    return next;
+};

package/dist/editor.d.ts

@@ -10,6 +10,10 @@ export { default as StructuredEditorPopover } from './components/admin-bar/struc
 export { default as FieldInput } from './components/admin-bar/field-input.svelte';
 export type { FieldInputType } from './components/admin-bar/field-input.svelte';
 export { default as ReorderButtons } from './components/admin-bar/reorder-buttons.svelte';
+export { default as FieldsForm } from './components/admin-bar/fields-form.svelte';
+export { default as ListField } from './components/admin-bar/list-field.svelte';
+export { default as LinkInput } from './components/admin-bar/link-input.svelte';
+export { default as RichTextInput } from './components/admin-bar/rich-text-input.svelte';
 export { default as CssRoot } from './components/admin-bar/css-root.svelte';
 export { Button } from './components/admin-bar/ui/button/index.js';
 export { Input } from './components/admin-bar/ui/input/index.js';

package/dist/editor.js

@@ -9,6 +9,10 @@
 export { default as StructuredEditorPopover } from './components/admin-bar/structured-editor-popover.svelte';
 export { default as FieldInput } from './components/admin-bar/field-input.svelte';
 export { default as ReorderButtons } from './components/admin-bar/reorder-buttons.svelte';
+export { default as FieldsForm } from './components/admin-bar/fields-form.svelte';
+export { default as ListField } from './components/admin-bar/list-field.svelte';
+export { default as LinkInput } from './components/admin-bar/link-input.svelte';
+export { default as RichTextInput } from './components/admin-bar/rich-text-input.svelte';
 export { default as CssRoot } from './components/admin-bar/css-root.svelte';
 export { Button } from './components/admin-bar/ui/button/index.js';
 export { Input } from './components/admin-bar/ui/input/index.js';

package/dist/index.d.ts

@@ -7,23 +7,37 @@
 export { default as CmsText } from './components/cms/cms-text.svelte';
 export { default as CmsRichText } from './components/cms/cms-rich-text.svelte';
 export { default as CmsMarkdown } from './components/cms/cms-markdown.svelte';
-export { default as CmsImage, normalizeImage } from './components/cms/cms-image.svelte';
-export type { CmsImageValue } from './components/cms/cms-image.svelte';
+export { default as CmsImage } from './components/cms/cms-image.svelte';
 export { default as CmsBoolean } from './components/cms/cms-boolean.svelte';
 export { default as CmsNumber } from './components/cms/cms-number.svelte';
 export type { CmsNumberProps } from './components/cms/cms-number.svelte';
 export { default as CmsDateTime } from './components/cms/cms-date-time.svelte';
 export type { CmsDateTimeMode, CmsDateTimeProps } from './components/cms/cms-date-time.svelte';
-export { default as CmsLink, normalizeLink } from './components/cms/cms-link.svelte';
-export type { CmsLinkValue, CmsLinkRenderProps } from './components/cms/cms-link.svelte';
-export { default as CmsRepeater } from './components/cms/cms-repeater.svelte';
+export { default as CmsLink } from './components/cms/cms-link.svelte';
+export type { CmsLinkRenderProps } from './components/cms/cms-link.svelte';
 export { default as CmsEntries } from './components/cms/cms-entries.svelte';
+export { default as CmsNav } from './components/cms/cms-nav.svelte';
+export { default as CmsHours } from './components/cms/cms-hours.svelte';
+export { default as CmsContact } from './components/cms/cms-contact.svelte';
+export { default as CmsSocialLinks } from './components/cms/cms-social-links.svelte';
+export { default as CmsCollection } from './components/cms/cms-collection.svelte';
+export { default as CmsTeam } from './components/cms/cms-team.svelte';
+export { default as CmsTestimonials } from './components/cms/cms-testimonials.svelte';
+export { default as CmsPricing } from './components/cms/cms-pricing.svelte';
+export { default as CmsFaq } from './components/cms/cms-faq.svelte';
+export { default as CmsStats } from './components/cms/cms-stats.svelte';
+export { default as CmsSteps } from './components/cms/cms-steps.svelte';
+export { default as CmsTimeline } from './components/cms/cms-timeline.svelte';
+export { default as CmsGallery } from './components/cms/cms-gallery.svelte';
+export { default as CmsLogos } from './components/cms/cms-logos.svelte';
+export { default as CmsSchedule } from './components/cms/cms-schedule.svelte';
+export * from './core/shapes/index.js';
 export { default as AdminBar } from './components/admin-bar/admin-bar.svelte';
 export { useCmsField, resolveScopeRef, ROOT_SCOPE_ID } from './components/cms/use-cms-field.svelte.js';
 export type { CmsField, CmsFieldInput } from './components/cms/use-cms-field.svelte.js';
-export { defineStructured, applyTranslations, countTranslations, extractTranslations, stripTranslations, translatableFields, translationPath, asBoolean, asItems, asNumber, asString, newItemId, ROOT_ID, TRANSLATIONS_KEY } from './core/structured.js';
-export type { Structured, StructuredItem, StructuredSchema, TranslatableField, TranslationOverlay } from './core/structured.js';
-export { registerStructured, getStructured } from './components/cms/structured-registry.js';
+export { defineStructured, applyTranslations, countTranslations, extractTranslations, stripTranslations, translatableFields, translationPath, asBoolean, asEnum, asItems, asNumber, asOptionalString, asString, asStrings, moveItem, newItemId, setIn, ROOT_ID, TRANSLATIONS_KEY } from './core/structured.js';
+export type { ItemsSpec, Structured, StructuredItem, StructuredSchema, TranslatableField, TranslationOverlay } from './core/structured.js';
+export { registerStructured, getStructured } from './core/structured-registry.js';
 export { toMetaTags } from './core/metadata.js';
 export type { MetaTagsOptions, MetaTagsOutput } from './core/metadata.js';
 export { definePage, DEFAULT_METADATA_SCHEMA, metadataSchemaFor } from './components/admin-bar/page-config.js';

package/dist/index.js

@@ -8,13 +8,32 @@
 export { default as CmsText } from './components/cms/cms-text.svelte';
 export { default as CmsRichText } from './components/cms/cms-rich-text.svelte';
 export { default as CmsMarkdown } from './components/cms/cms-markdown.svelte';
-export { default as CmsImage, normalizeImage } from './components/cms/cms-image.svelte';
+export { default as CmsImage } from './components/cms/cms-image.svelte';
 export { default as CmsBoolean } from './components/cms/cms-boolean.svelte';
 export { default as CmsNumber } from './components/cms/cms-number.svelte';
 export { default as CmsDateTime } from './components/cms/cms-date-time.svelte';
-export { default as CmsLink, normalizeLink } from './components/cms/cms-link.svelte';
-export { default as CmsRepeater } from './components/cms/cms-repeater.svelte';
+export { default as CmsLink } from './components/cms/cms-link.svelte';
 export { default as CmsEntries } from './components/cms/cms-entries.svelte';
+// Structured editor components. Each reads one versioned value, opens a
+// popover editor in edit mode and hands the typed view to `children`.
+// Their value types, normalizers and JSON-LD helpers come from the shapes.
+export { default as CmsNav } from './components/cms/cms-nav.svelte';
+export { default as CmsHours } from './components/cms/cms-hours.svelte';
+export { default as CmsContact } from './components/cms/cms-contact.svelte';
+export { default as CmsSocialLinks } from './components/cms/cms-social-links.svelte';
+export { default as CmsCollection } from './components/cms/cms-collection.svelte';
+export { default as CmsTeam } from './components/cms/cms-team.svelte';
+export { default as CmsTestimonials } from './components/cms/cms-testimonials.svelte';
+export { default as CmsPricing } from './components/cms/cms-pricing.svelte';
+export { default as CmsFaq } from './components/cms/cms-faq.svelte';
+// List presets: fixed item shapes; a new shape is a new preset here.
+export { default as CmsStats } from './components/cms/cms-stats.svelte';
+export { default as CmsSteps } from './components/cms/cms-steps.svelte';
+export { default as CmsTimeline } from './components/cms/cms-timeline.svelte';
+export { default as CmsGallery } from './components/cms/cms-gallery.svelte';
+export { default as CmsLogos } from './components/cms/cms-logos.svelte';
+export { default as CmsSchedule } from './components/cms/cms-schedule.svelte';
+export * from './core/shapes/index.js';
 // Admin bar (sync wrapper; admin-bar-internal + seo-panel are async chunks)
 export { default as AdminBar } from './components/admin-bar/admin-bar.svelte';
 // Building blocks for structured components: the field hook, the value
@@ -23,8 +42,8 @@ export { default as AdminBar } from './components/admin-bar/admin-bar.svelte';
 // lazily by editable siblings:
 //   `import('@velastack/cms/editor')`
 export { useCmsField, resolveScopeRef, ROOT_SCOPE_ID } from './components/cms/use-cms-field.svelte.js';
-export { defineStructured, applyTranslations, countTranslations, extractTranslations, stripTranslations, translatableFields, translationPath, asBoolean, asItems, asNumber, asString, newItemId, ROOT_ID, TRANSLATIONS_KEY } from './core/structured.js';
-export { registerStructured, getStructured } from './components/cms/structured-registry.js';
+export { defineStructured, applyTranslations, countTranslations, extractTranslations, stripTranslations, translatableFields, translationPath, asBoolean, asEnum, asItems, asNumber, asOptionalString, asString, asStrings, moveItem, newItemId, setIn, ROOT_ID, TRANSLATIONS_KEY } from './core/structured.js';
+export { registerStructured, getStructured } from './core/structured-registry.js';
 // Page metadata → svelte-meta-tags props.
 export { toMetaTags } from './core/metadata.js';
 // Per-route page configuration — declare in `page.cms.ts` next to `+page.svelte`.

package/dist/server/README.md

@@ -29,7 +29,7 @@ export const { load: loadCms, generateEntries } = createCms({
 ```ts
 // src/routes/+layout.server.ts
 import { error, redirect } from '@sveltejs/kit';
-import { loadCms } from '$lib/cms.js';
+import { loadCms } from '#lib/cms.js';
 
 export const load = async (event) => {
 	// Pick the locale however you like — pathname, Accept-Language, cookie, …

package/dist/server/api-adapter.js

@@ -1,4 +1,4 @@
-import { building } from '$app/environment';
+import { building } from '$app/env';
 import { buildConfig } from 'virtual:vela-cms/build-config';
 /**
  * The Vite plugin generates `virtual:vela-cms/build-config` with the

package/dist/server/cms.d.ts

@@ -52,7 +52,7 @@ export type Cms = {
  * Typical usage:
  *
  * ```ts
- * // $lib/cms.ts
+ * // src/lib/cms.ts
  * import { createCms, mockAdapter } from '@velastack/cms/server';
  * export const { load: loadCms, generateEntries } = createCms({
  *   adapter: mockAdapter({ layoutDocs, pageDocs }),

package/dist/server/cms.js

@@ -7,7 +7,7 @@ import { loadCms } from './load-cms.js';
  * Typical usage:
  *
  * ```ts
- * // $lib/cms.ts
+ * // src/lib/cms.ts
  * import { createCms, mockAdapter } from '@velastack/cms/server';
  * export const { load: loadCms, generateEntries } = createCms({
  *   adapter: mockAdapter({ layoutDocs, pageDocs }),

package/dist/server/load-cms.js

@@ -1,6 +1,6 @@
 import { cmsManifest } from 'virtual:vela-cms/manifest';
 import { mergeLocaleDocs, mergeLocaleEntries } from '../components/cms/locale-merge.js';
-import { browser, building } from '$app/environment';
+import { browser, building } from '$app/env';
 const builtManifest = cmsManifest;
 const DEFAULT_ENDPOINT = '/api/cms';
 const emptyPayload = (locale, locales, endpoint, site) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@velastack/cms",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "A scope-aware CMS for SvelteKit, for static or dynamic sites.",
 	"keywords": [
 		"svelte",
@@ -22,7 +22,7 @@
 	},
 	"type": "module",
 	"engines": {
-		"node": ">=22.12.0"
+		"node": ">=22.17.0"
 	},
 	"scripts": {
 		"dev": "vite dev",
@@ -84,11 +84,11 @@
 		}
 	},
 	"peerDependencies": {
-		"@sveltejs/kit": "^2.0.0",
+		"@sveltejs/kit": "^3.0.0",
 		"better-sqlite3": "^12.0.0 || ^13.0.0",
 		"marked": "^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0",
-		"svelte": "^5.0.0",
-		"vite": "^8.0.0"
+		"svelte": "^5.57.1",
+		"vite": "^8.0.12"
 	},
 	"peerDependenciesMeta": {
 		"better-sqlite3": {
@@ -100,10 +100,9 @@
 	},
 	"devDependencies": {
 		"@internationalized/date": "^3.12.3",
-		"@sveltejs/adapter-auto": "^7.0.1",
-		"@sveltejs/kit": "^2.70.3",
-		"@sveltejs/package": "^2.5.8",
-		"@sveltejs/vite-plugin-svelte": "^7.3.0",
+		"@sveltejs/kit": "^3.0.0",
+		"@sveltejs/package": "^3.0.0",
+		"@sveltejs/vite-plugin-svelte": "^7.3.1",
 		"@tailwindcss/cli": "^4.3.3",
 		"@tailwindcss/vite": "^4.3.3",
 		"@types/node": "^26.4.0",
@@ -112,7 +111,7 @@
 		"prettier": "^3.9.6",
 		"prettier-plugin-svelte": "^4.1.1",
 		"publint": "^0.3.24",
-		"svelte": "^5.57.0",
+		"svelte": "^5.57.1",
 		"svelte-check": "^4.7.6",
 		"svelte-meta-tags": "^5.0.2",
 		"tailwindcss": "^4.3.3",
@@ -122,7 +121,7 @@
 		"vitest": "^5.0.1"
 	},
 	"dependencies": {
-		"@sveltejs/adapter-static": "^3.0.10",
+		"@sveltejs/adapter-static": "^4.0.0",
 		"@tiptap/core": "^3.30.6",
 		"@tiptap/extension-link": "^3.30.6",
 		"@tiptap/pm": "^3.30.6",
@@ -130,5 +129,10 @@
 		"bits-ui": "^2.19.0",
 		"devalue": "^6.0.0",
 		"tailwind-merge": "^3.6.0"
+	},
+	"imports": {
+		"#lib": "./src/lib/index.js",
+		"#lib/*": "./src/lib/*",
+		"#locales/*": "./src/locales/*"
 	}
 }

package/plugin/README.md

@@ -44,7 +44,10 @@ type ExternalCmsComponentSpec =
 ```
 
 - `routesDir` / `libDir` — only override if your project diverges from the
-  SvelteKit defaults.
+  SvelteKit defaults. `#lib/…` imports resolve through the project's
+  `package.json` `imports` (read once when the config resolves), falling back
+  to `libDir` when `#lib` isn't declared there; `$lib/…` still resolves to
+  `libDir`.
 - `components` — third-party CMS component packs the walker should recognize.
   Auto-discovered for everything inside `<libDir>/components/cms/` and the
   `@velastack/cms` package itself; use this for components installed from npm.
@@ -111,7 +114,7 @@ instance script (or creates one if absent). Authors never write
 ### `routeId` into zero-arg `generateEntries()` calls
 
 In any `+page.ts` or `+page.server.ts` that imports `generateEntries` (from
-anywhere — typically `$lib/cms.ts`), zero-argument calls
+anywhere — typically `#lib/cms.js`), zero-argument calls
 `generateEntries()` are rewritten to `generateEntries('<routeId>')`. Calls
 with any explicit argument are left alone — that's the documented opt-out.
 
@@ -123,8 +126,10 @@ Imports get classified as CMS components by:
 
 0. **`@velastack/cms` by name** — every named import from the package
    specifier, with no resolver needed.
-1. **In-tree barrel** — anything from `<libDir>/components/cms/index.{ts,js}`.
-   Named imports are CMS components; default isn't.
+1. **In-tree barrel** — anything from `<libDir>/components/cms/index.{ts,js}`,
+   however it's imported (`#lib/components/cms/index.js`, `$lib/components/cms`,
+   a relative path or another `#` subpath import). Named imports are CMS
+   components; default isn't.
 2. **In-tree files** — `.svelte` files directly under `<libDir>/components/cms/`.
    Default imports are CMS components.
 3. **`@velastack/cms` package** — any import resolving inside the `@velastack/cms`
@@ -139,6 +144,31 @@ own. Dynamic `name={expr}` props and `scope=` attributes naming a scope
 outside the route's chain are reported as warnings on the build result and
 logged by the plugin.
 
+## Static adapter
+
+`@velastack/cms/adapter` wraps `@sveltejs/adapter-static` and takes the same
+options. It goes in `sveltekit({...})` next to `cms()`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { cms } from '@velastack/cms/vite';
+import cmsAdapter from '@velastack/cms/adapter';
+
+export default defineConfig({
+	plugins: [cms(), sveltekit({ adapter: cmsAdapter({ fallback: '200.html' }) })]
+});
+```
+
+After the inner adapter runs it writes `__fallback.json` beside each
+parameterized route's parent directory (built from a prerendered
+`__data.json`, with docs and metadata cleared and params replaced by
+`%name%`), and injects `__velastack_manifest` plus a small fetch shim into the
+`fallback` page. The manifest lists the prerendered entries of every
+`creatable` `page.cms.ts` route; the plugin hands those routes to the adapter
+in-process, so the adapter warns when the `cms()` plugin never ran.
+
 ## HMR
 
 The plugin invalidates `virtual:vela-cms/manifest` and

package/plugin/dist/adapter.d.ts

@@ -7,13 +7,13 @@
  * `%name%`. The runtime can fetch the fallback when navigating to a CMS page
  * that wasn't prerendered, then substitute the actual params client-side.
  *
+ * Everything else (`supports`, `emulate`, `vite`, whatever adapter-static
+ * grows) comes from the inner adapter unchanged.
+ *
  * @param {StaticAdapterOptions} [options]
+ * @returns {import('@sveltejs/kit').Adapter}
  */
-export default function adapter(options?: StaticAdapterOptions): {
-    name: string;
-    /** @param {import('@sveltejs/kit').Builder} builder */
-    adapt(builder: import("@sveltejs/kit").Builder): Promise<void>;
-};
+export default function adapter(options?: StaticAdapterOptions): import("@sveltejs/kit").Adapter;
 export function parseRouteSegments(routeId: string): ParsedSegment[];
 export function buildParamExtractor(segments: ParsedSegment[]): ((url: string) => Record<string, string> | null) | null;
 export type StaticAdapterOptions = Parameters<typeof staticAdapter>[0];