@velastack/cms 0.3.1 → 0.5.0

package/dist/core/structured.js

@@ -0,0 +1,184 @@
+/**
+ * Structured values: the shapes behind the editor components (hours, team,
+ * testimonials, …) and the two rules every one of them follows.
+ *
+ * 1. **Versioned shapes, whole-object writes.** A structured value is a plain
+ *    object with a `v` version number. Components never patch a leaf inside
+ *    it; they read the whole value through the schema's `normalize`, change
+ *    it, and write the whole object back. A field the editor clears is
+ *    written as `null`, never dropped: the draft and release trees deep-merge
+ *    over the published tree, and a missing key merges to "unchanged" while
+ *    `null` merges to "cleared". That is what stops a cleared field from
+ *    reverting to the template's demo copy.
+ *
+ * 2. **Localisation is a string overlay, never a second structure.** The
+ *    default locale stores the full value at `<name>`. Every other locale
+ *    stores only strings, at `<name>.$t.<id>.<field>`, keyed by the stable
+ *    `id` of the list item they translate (the reserved id `_` addresses the
+ *    value's own root fields). Because objects deep-merge across locales,
+ *    reading `es` yields the default structure plus the `es` overlay, and
+ *    {@link applyTranslations} folds the strings in. Structure edits happen in
+ *    the default locale only, so the item list can never fork between
+ *    languages.
+ */
+import { get } 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. */
+export const ROOT_ID = '_';
+export const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+export const defineStructured = (schema) => ({
+    ...schema,
+    read: (raw, fallback) => {
+        if (raw === undefined)
+            return fallback === undefined ? schema.empty() : fallback;
+        if (raw === null)
+            return schema.empty();
+        const overlay = extractTranslations(raw);
+        const value = schema.normalize(stripTranslations(raw));
+        return overlay ? applyTranslations(value, overlay, schema) : value;
+    }
+});
+/** 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. */
+export const extractTranslations = (raw) => {
+    if (!isPlainObject(raw))
+        return undefined;
+    const t = raw[TRANSLATIONS_KEY];
+    if (!isPlainObject(t))
+        return undefined;
+    const out = {};
+    for (const [id, fields] of Object.entries(t)) {
+        if (!isPlainObject(fields))
+            continue;
+        const strings = {};
+        for (const [field, v] of Object.entries(fields)) {
+            if (typeof v === 'string')
+                strings[field] = v;
+        }
+        out[id] = strings;
+    }
+    return out;
+};
+/** A copy of `raw` without its `$t` branch, so a whole-object write in the
+ * default locale never carries another locale's strings. */
+export const stripTranslations = (raw) => {
+    if (!isPlainObject(raw) || !(TRANSLATIONS_KEY in raw))
+        return raw;
+    const { [TRANSLATIONS_KEY]: _omit, ...rest } = raw;
+    return rest;
+};
+const overlayString = (overlay, id, field) => {
+    const v = overlay[id]?.[field];
+    return typeof v === 'string' && v !== '' ? v : undefined;
+};
+/**
+ * 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.
+ */
+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 out;
+};
+/**
+ * Every translatable, non-empty string in a normalized default-locale value.
+ * Drives the popover's translation tab and the Locales panel's counts.
+ */
+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 });
+                }
+            }
+        }
+    }
+    return out;
+};
+/** How many translatable strings a locale's overlay still lacks. */
+export const countTranslations = (value, overlay, schema) => {
+    const fields = translatableFields(value, schema);
+    let missing = 0;
+    for (const f of fields) {
+        if (!overlay || overlayString(overlay, f.id, f.field) === undefined)
+            missing += 1;
+    }
+    return { total: fields.length, missing };
+};
+// ---------------------------------------------------------------------------
+// Normalizer building blocks
+// ---------------------------------------------------------------------------
+export const asString = (v, fallback = '') => typeof v === 'string' ? v : fallback;
+export const asNumber = (v, fallback = null) => typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+export const asBoolean = (v, fallback = false) => typeof v === 'boolean' ? v : fallback;
+/**
+ * Normalize a list of items, guaranteeing every item carries a string `id`.
+ * An item without one (a hand-written seed, say) gets a deterministic
+ * `item-<index>` so reads stay stable until the editor next writes the list,
+ * at which point the ids are persisted.
+ */
+export const asItems = (raw, normalizeItem) => {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    raw.forEach((entry, index) => {
+        if (!isPlainObject(entry))
+            return;
+        const id = typeof entry.id === 'string' && entry.id !== '' ? entry.id : `item-${index}`;
+        out.push({ id, ...normalizeItem(entry, index) });
+    });
+    return out;
+};
+/** A short random id for a newly added item. Stable once written. */
+export const newItemId = () => {
+    const bytes = new Uint8Array(6);
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues)
+        crypto.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    let out = '';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+};
+/** Read a structured value's overlay for one locale out of a whole scope tree. */
+export const overlayAt = (tree, name) => extractTranslations(get(tree, name));

package/dist/core/wire.d.ts

@@ -11,7 +11,7 @@
  * `published_at` stay snake_case because that is what the JSON carries.
  */
 import type { Tree } from './path.js';
-import type { PageDeleteOutcome } from './page-entry.js';
+import type { PageDeleteOutcome, PageEntry } from './page-entry.js';
 export type { PageDeleteOutcome };
 /** One pending change in a release, without the bookkeeping the store adds. */
 export type ReleaseItemCore = {
@@ -54,10 +54,20 @@ export type PublishedReleaseItem = ReleaseItemCore & {
     priorTree: Tree | null;
     priorTombstone?: PageDeleteOutcome;
 };
+/**
+ * The editor who published a release, captured at publish time. `email` and
+ * `name` are null only on rows published before they were recorded, where the
+ * account no longer resolves.
+ */
+export type ReleasePublisher = {
+    id: string;
+    email: string | null;
+    name: string | null;
+};
 export type PublishedRelease = {
     id: string;
     name?: string;
-    publishedBy: string;
+    publishedBy: ReleasePublisher;
     publishedAt: string;
     preview_key: string;
     items: PublishedReleaseItem[];
@@ -172,6 +182,36 @@ export type CmsDeployState = {
     };
     latest?: CmsDeployRun | null;
 };
+/**
+ * A project's published content in one object: `layouts` and `pages` keyed
+ * `[locale][routeId]`, plus the non-localised `site` tree. `POST /seed`
+ * accepts it and `GET /export` returns it, so a template's published
+ * `content/` can seed a fresh project and a project can be dumped back into
+ * the same shape. A page keyed by route id may be a bare tree (a static page,
+ * `params: {}`) or a full `PageEntry[]`.
+ */
+export type CmsSeed = {
+    layouts?: Record<string, Record<string, Tree>>;
+    pages?: Record<string, Record<string, Tree | PageEntry[]>>;
+    site?: Tree;
+};
+export type SeedRequest = CmsSeed & {
+    /** Overwrite a project that already has published rows. */
+    force?: boolean;
+};
+export type SeedSummary = {
+    locales: string[];
+    layouts: number;
+    pages: number;
+    site: boolean;
+};
+export type SeedResponse = {
+    ok: true;
+    seeded: SeedSummary;
+} | {
+    ok: false;
+    reason: 'already-seeded';
+};
 export type DocsResponse = {
     contents: Tree;
 } | PageDeleteOutcome;

package/dist/editor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@velastack/cms/editor` — the editing chrome a structured component's
+ * editable sibling imports lazily, so none of it reaches the public bundle:
+ *
+ * ```svelte
+ * {#await import('@velastack/cms/editor') then { StructuredEditorPopover, FieldInput, ReorderButtons }}
+ * ```
+ */
+export { default as StructuredEditorPopover } from './components/admin-bar/structured-editor-popover.svelte';
+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 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';
+export { Textarea } from './components/admin-bar/ui/textarea/index.js';
+export { Switch } from './components/admin-bar/ui/switch/index.js';
+export { Checkbox } from './components/admin-bar/ui/checkbox/index.js';
+export * as Popover from './components/admin-bar/ui/popover/index.js';
+export * as Tabs from './components/admin-bar/ui/tabs/index.js';
+export * as Sheet from './components/admin-bar/ui/sheet/index.js';
+export { default as CmsMediaPicker } from './components/cms/cms-media-picker.svelte';

package/dist/editor.js

@@ -0,0 +1,21 @@
+/**
+ * `@velastack/cms/editor` — the editing chrome a structured component's
+ * editable sibling imports lazily, so none of it reaches the public bundle:
+ *
+ * ```svelte
+ * {#await import('@velastack/cms/editor') then { StructuredEditorPopover, FieldInput, ReorderButtons }}
+ * ```
+ */
+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 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';
+export { Textarea } from './components/admin-bar/ui/textarea/index.js';
+export { Switch } from './components/admin-bar/ui/switch/index.js';
+export { Checkbox } from './components/admin-bar/ui/checkbox/index.js';
+export * as Popover from './components/admin-bar/ui/popover/index.js';
+export * as Tabs from './components/admin-bar/ui/tabs/index.js';
+export * as Sheet from './components/admin-bar/ui/sheet/index.js';
+export { default as CmsMediaPicker } from './components/cms/cms-media-picker.svelte';

package/dist/index.d.ts

@@ -7,21 +7,29 @@
 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 } from './components/cms/cms-image.svelte';
+export { default as CmsImage, normalizeImage } from './components/cms/cms-image.svelte';
+export type { CmsImageValue } 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 } from './components/cms/cms-link.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 CmsEntries } from './components/cms/cms-entries.svelte';
 export { default as AdminBar } from './components/admin-bar/admin-bar.svelte';
-export { definePage } from './components/admin-bar/page-config.js';
+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 { 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';
 export type { CmsPageConfig, CmsCreatablePageConfig, CmsStaticPageConfig, CmsPageField, CmsPageMetadataSchema, MetadataFieldSchema, MetadataPrimitive } from './components/admin-bar/page-config.js';
 export { cmsStore } from './components/cms/cms-store.svelte.js';
 export { cms } from './components/cms/cms-store.svelte.js';
 export { CMS_SCOPE, getCmsScope, getCmsValue, getPageScope } from './components/cms/scope.js';
 export { installCmsScope } from './components/cms/install-scope.svelte.js';
-export type { CmsEntry, CmsManifest, CmsManifestRoute, CmsManifestScope, CmsPayload, CmsScope, CmsScopeEntry } from './components/cms/scope.js';
+export type { CmsEntry, CmsManifest, CmsManifestRoute, CmsManifestScope, CmsManifestUsage, CmsPayload, CmsScope, CmsScopeEntry, SiteFieldSchema, SiteFieldType, SiteSchema } from './components/cms/scope.js';

package/dist/index.js

@@ -8,17 +8,27 @@
 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 } from './components/cms/cms-image.svelte';
+export { default as CmsImage, normalizeImage } 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 } from './components/cms/cms-link.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 CmsEntries } from './components/cms/cms-entries.svelte';
 // 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
+// rules (versioned shapes, `$t` overlay) and the registry the Locales panel
+// reads. The editor popover and field inputs are admin-bar chunks, imported
+// 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';
+// 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`.
-export { definePage } from './components/admin-bar/page-config.js';
+export { definePage, DEFAULT_METADATA_SCHEMA, metadataSchemaFor } from './components/admin-bar/page-config.js';
 // Edit-mode store
 export { cmsStore } from './components/cms/cms-store.svelte.js';
 // Merged CMS read view (server payload + client overlay), shaped like CmsPayload

package/dist/server/load-cms.js

@@ -61,6 +61,7 @@ export const resolveCmsPayload = async (args) => {
             routeId: scope.routeId,
             params: scopeParams,
             fields: scope.fields,
+            ...(scope.usages ? { usages: scope.usages } : {}),
             locale: forLocale
         };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@velastack/cms",
-	"version": "0.3.1",
+	"version": "0.5.0",
 	"description": "A scope-aware CMS for SvelteKit, for static or dynamic sites.",
 	"keywords": [
 		"svelte",
@@ -22,7 +22,7 @@
 	},
 	"type": "module",
 	"engines": {
-		"node": "^20.19.0 || >=22.12.0"
+		"node": ">=22.12.0"
 	},
 	"scripts": {
 		"dev": "vite dev",
@@ -57,6 +57,11 @@
 			"svelte": "./dist/index.js",
 			"default": "./dist/index.js"
 		},
+		"./editor": {
+			"types": "./dist/editor.d.ts",
+			"svelte": "./dist/editor.js",
+			"default": "./dist/editor.js"
+		},
 		"./server": {
 			"types": "./dist/server/index.d.ts",
 			"default": "./dist/server/index.js"
@@ -72,11 +77,15 @@
 		"./adapter": {
 			"types": "./plugin/dist/adapter.d.ts",
 			"default": "./plugin/dist/adapter.js"
+		},
+		"./build": {
+			"types": "./plugin/dist/build.d.ts",
+			"default": "./plugin/dist/build.js"
 		}
 	},
 	"peerDependencies": {
 		"@sveltejs/kit": "^2.0.0",
-		"better-sqlite3": "^11.0.0 || ^12.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"
@@ -98,7 +107,7 @@
 		"@tailwindcss/cli": "^4.3.3",
 		"@tailwindcss/vite": "^4.3.3",
 		"@types/node": "^26.4.0",
-		"better-sqlite3": "^12.11.1",
+		"better-sqlite3": "^13.0.3",
 		"marked": "^18.0.11",
 		"prettier": "^3.9.6",
 		"prettier-plugin-svelte": "^4.1.1",
@@ -110,7 +119,7 @@
 		"tw-animate-css": "^1.4.0",
 		"typescript": "^6.0.3",
 		"vite": "^8.2.2",
-		"vitest": "^4.1.11"
+		"vitest": "^5.0.1"
 	},
 	"dependencies": {
 		"@sveltejs/adapter-static": "^3.0.10",
@@ -119,7 +128,7 @@
 		"@tiptap/pm": "^3.30.6",
 		"@tiptap/starter-kit": "^3.30.6",
 		"bits-ui": "^2.19.0",
-		"devalue": "^5.9.2",
+		"devalue": "^6.0.0",
 		"tailwind-merge": "^3.6.0"
 	}
 }

package/plugin/README.md

@@ -31,6 +31,11 @@ type CmsPluginOptions = {
 	libDir?: string; // default: 'src/lib'
 	components?: ExternalCmsComponentSpec[];
 	traverse?: (string | RegExp)[];
+	endpoint?: string; // media download at build time
+	locales?: string[]; // default: ['en']; locales[0] is the default locale
+	mediaDir?: string;
+	mediaPrefix?: string;
+	content?: string | false; // default: 'content' — see "Content manifest"
 };
 
 type ExternalCmsComponentSpec =
@@ -48,6 +53,14 @@ type ExternalCmsComponentSpec =
   `source === pattern || source.startsWith(pattern + '/')`. Auto-populated with
   every `components[].source`.
 
+- `content` — directory of per-locale content manifests. See below.
+
+## Content manifest
+
+When `<content>/<defaultLocale>.json` exists, the plugin reads it — an object keyed by scope id (`layout:/`, `page:/(public)/about`, `site`) — and injects each usage's value as a `fallback={…}` prop (`initial` for `CmsBoolean`) into every walked `.svelte` file, route entrypoints and shared components alike. A `scope="root"` usage reads `layout:/`; any other usage reads the scopes that reach its file, leaf first. Components in source stay name-only; the value the visitor sees before the CMS answers comes from the manifest. The file is watched, so edits apply in dev.
+
+The same operation is available to other tooling from `@velastack/cms/build` (`scanUsages`, `injectFallbacks` / `inlineFallbacks`, `buildManifest`, `fallbackResolverFor`), so `pack` and `verify` in a templates repo share this parser instead of carrying their own.
+
 ## Virtual modules
 
 ### `virtual:vela-cms/manifest`
@@ -57,6 +70,7 @@ import { cmsManifest } from 'virtual:vela-cms/manifest';
 
 type CmsManifest = {
 	version: 1;
+	// each scope lists `fields` (names) and `usages` ({ name, component, preset? })
 	routes: Record<string, { scopes: CmsManifestScope[] }>;
 };
 
@@ -107,6 +121,8 @@ For each route entrypoint (`+page.svelte` or `+layout.svelte`), the plugin
 parses with `svelte/compiler` and follows static imports of `.svelte` files.
 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.
 2. **In-tree files** — `.svelte` files directly under `<libDir>/components/cms/`.
@@ -116,8 +132,12 @@ Imports get classified as CMS components by:
 4. **External `components` spec** — user-declared packs.
 
 Component usages with a `name=<static>` prop are recorded as field
-references; `value=<…>` opts the call out (it's a runtime override, not a
-field). Dynamic `name={expr}` props are ignored.
+references with their component type; `value=<…>` opts the call out (it's a
+runtime override, not a field). A `scope="root"` (or `scope="layout:/x"`)
+attribute records the usage under that layout scope instead of the file's
+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.
 
 ## HMR
 

package/plugin/dist/build.d.ts

@@ -0,0 +1,74 @@
+import { buildManifest, resolveScopeAttr, ROOT_SCOPE_ID, type BuildManifestOptions, type BuildManifestResult, type CmsManifest, type CmsManifestScope, type CmsManifestUsage } from './manifest.js';
+export { buildManifest, resolveScopeAttr, ROOT_SCOPE_ID };
+export type Tree = Record<string, unknown>;
+export type { BuildManifestOptions, BuildManifestResult, CmsManifest, CmsManifestScope, CmsManifestUsage };
+export type CmsUsage = {
+    /** Static `name=` literal, or `null` when absent or dynamic. */
+    name: string | null;
+    /** Canonical exported component name (`CmsText`, `CmsHours`, …). */
+    component: string;
+    /** Local binding used in the template. */
+    local: string;
+    /** Resolved scope id from `scope=`, or `null` for the enclosing route scope. */
+    scope: string | null;
+    preset: string | null;
+    /** `name=` was present but not a static string. */
+    dynamic: boolean;
+    hasValue: boolean;
+    hasFallback: boolean;
+    line: number;
+    /** Source offsets of the component node. */
+    start: number;
+    end: number;
+};
+export type ScanOptions = {
+    filename?: string;
+    /**
+     * Extra local names to treat as CMS components, for wrappers a template
+     * declares itself. Package imports and `$lib/components/cms/*` are always
+     * recognized.
+     */
+    components?: string[];
+};
+export type ScanResult = {
+    usages: CmsUsage[];
+    /** Dynamic names, which no manifest can record. */
+    warnings: string[];
+};
+/** Every CMS component usage in one `.svelte` source. */
+export declare const scanUsages: (source: string, options?: ScanOptions) => ScanResult;
+/** Returns the value to inject for a usage, or `undefined` to leave it alone. */
+export type FallbackResolver = (usage: CmsUsage) => unknown;
+export type InjectOptions = ScanOptions & {
+    /** Replace an existing `fallback` / `initial` prop instead of skipping it. */
+    overwrite?: boolean;
+};
+export type InjectResult = {
+    code: string;
+    /** Names that received a fallback. */
+    injected: string[];
+    /** Static names the resolver had no value for. */
+    missing: string[];
+};
+/**
+ * Write values into a file's CMS usages as `fallback={…}` props (the JSON
+ * literal of the value), leaving the source otherwise untouched. `resolve`
+ * is a content tree keyed by name, or a function for callers that know
+ * which scope each usage's value lives in (see {@link fallbackResolverFor}).
+ *
+ * Usages with a `value=` prop, a dynamic name, or (unless `overwrite`) an
+ * existing fallback are skipped. The plugin calls this in memory at build
+ * time in the templates repo; `pack` calls it to write the tarball's
+ * components, which is why it is also exported as {@link inlineFallbacks}.
+ */
+export declare const injectFallbacks: (source: string, resolve: Tree | FallbackResolver, options?: InjectOptions) => InjectResult;
+/** Same operation as {@link injectFallbacks}, named for the `pack` step that
+ * writes the result to disk. */
+export declare const inlineFallbacks: (source: string, resolve: Tree | FallbackResolver, options?: InjectOptions) => InjectResult;
+/**
+ * A resolver for one file, given a built manifest and a content manifest
+ * keyed by scope id (`layout:/`, `page:/(public)/about`, …). A usage with
+ * `scope=` reads that scope; otherwise the scopes that reach the file are
+ * tried leaf first, and the first one holding the value wins.
+ */
+export declare const fallbackResolverFor: (result: Pick<BuildManifestResult, "scopesByFile">, file: string, content: Record<string, Tree>) => FallbackResolver;