@phtngyn/cms 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -2,12 +2,16 @@
 
 A CMS for Nuxt with an embedded Studio, collaborative editing, PostgreSQL persistence, and S3-compatible media storage. Install one module, configure your services in `cms.config.ts`, and create your first administrator in Studio. Database migrations and authentication are managed by the module.
 
+## Working on this package
+
+This is the consumer guide. For implementation changes, start at [Module](./src/Module.ts) for Nuxt registration, [Configuration](./src/Configuration.ts) and [configuration compilation](./src/internal/configuration.ts) for setup, [runtime](./src/runtime/) for delivery, and [package exports and scripts](./package.json) for the current public surface. Follow the feature into its owning package and tests before changing behavior; examples below illustrate usage rather than define the current contract. The [canonical example](../../examples/nuxt/README.md) exercises the module end to end.
+
 ## Install
 
 Requires Node.js 24, Nuxt `>=4.5.0 <5`, and Vue `>=3.6.0-rc.6 <4`. Deploy as a Node server with WebSocket support; static hosting is not supported.
 
 ```sh
-pnpm add @phtngyn/cms@beta zod
+pnpm add @phtngyn/cms@beta effect
 ```
 
 Register the module in `nuxt.config.ts`:
@@ -26,7 +30,7 @@ Create `cms.config.ts` beside `nuxt.config.ts`:
 
 ```ts
 import { defineCmsConfig } from '@phtngyn/cms/Configuration'
-import { z } from 'zod'
+import { Schema } from 'effect'
 
 function env(name: string): string {
   const value = process.env[name]
@@ -44,7 +48,7 @@ export default defineCmsConfig({
       pages: {
         label: 'Page',
         route: '/:path*',
-        schema: z.object({ title: z.string().min(1) }),
+        schema: Schema.Struct({ title: Schema.NonEmptyString }),
         source: '.',
       },
     },
@@ -70,9 +74,81 @@ These environment variable names are examples; configuration is executable TypeS
 
 For storage using the AWS credential chain, omit `credentials`. To create a missing bucket automatically, set `provisionBucket: true` and grant bucket-creation permission. Set `media: false` to start without uploads.
 
+## Search and sharing
+
+The module installs the focused Nuxt robots, sitemap, schema.org, and SEO utility modules. Published CMS pages receive canonical, robots, social-sharing, and structured-data metadata automatically. The sitemap contains only published, indexable documents and uses their publication revision time for `lastmod`; localized variants are emitted as alternatives when they share a document key.
+
+Administrators can edit and publish site-wide SEO defaults at `/_cms/app/seo`. Editors can override search and sharing fields per document, while omitted values inherit the site-wide revision. Draft preview uses working SEO settings; ordinary website requests use published settings.
+
+The initial site-wide revision is derived from `baseUrl`. To seed explicit defaults and restrict the structured identity choices Studio offers, add `seo` to `cms.config.ts`:
+
+```ts
+seo: {
+  defaults: {
+    canonicalOrigin: 'https://example.com',
+    siteName: 'Example',
+    titleTemplate: '%s · Example',
+    defaultDescription: 'Example publishes useful things.',
+    index: true,
+    follow: true,
+    identity: {
+      type: 'Organization',
+      name: 'Example',
+      url: 'https://example.com',
+    },
+  },
+  capabilities: {
+    identityTypes: ['Organization'],
+    structuredDataTypes: ['WebPage', 'Article'],
+    generatedSocialImageTemplateIds: [],
+  },
+},
+```
+
+Keep raw robots directives and Nuxt module configuration in application code. The CMS owns semantic index/follow choices and generated page metadata; it does not accept arbitrary JSON-LD or inline HTML.
+
+## Collection schemas
+
+Effect schemas work directly. The CMS derives Studio inputs from their encoded structure and runs the original decoder when validating documents, preserving defaults, transformations, and asynchronous validation. Decoders must not require external Effect services, and their output must be a JSON-compatible object.
+
+```ts
+import { Effect, Schema } from 'effect'
+import { CalendarDate, field } from '@phtngyn/cms/DocumentModel'
+
+const pageSchema = Schema.Struct({
+  description: field(Schema.String.annotate({ default: '' }), { input: 'textarea' }).pipe(
+    Schema.withDecodingDefaultKey(Effect.succeed('')),
+  ),
+  publishedAt: Schema.optionalKey(field(CalendarDate, { label: 'Published on' })),
+  title: Schema.NonEmptyString,
+})
+```
+
+Use `Schema.optionalKey` for optional fields and `Schema.Finite` for numeric fields. An encoded `default` annotation supplies Studio's initial value; `Schema.withDecodingDefaultKey` applies that default during validation. `CalendarDate` validates calendar dates stored as `YYYY-MM-DD` strings. `field` adds presentation annotations to the encoded side of an Effect schema.
+
+Other libraries are supported through a schema implementing **both Standard Schema V1 and Standard JSON Schema V1**. Standard Schema supplies validation and typed output; Standard JSON Schema's `jsonSchema.input({ target: 'draft-2020-12' })` supplies the editor structure. A library that only implements validation needs an adapter adding JSON Schema conversion; Standard Schema alone cannot generate a form.
+
+For example, an existing Standard Schema validator can be adapted with its library's JSON Schema converters:
+
+```ts
+const collectionSchema = {
+  '~standard': {
+    ...validator['~standard'],
+    jsonSchema: {
+      input: () => inputJsonSchema,
+      output: () => outputJsonSchema,
+    },
+  },
+}
+```
+
+Supply actual draft 2020-12 schemas from the chosen library, using its input and output conversion modes respectively. Foreign schemas use JSON Schema `title`, `description`, `default`, and `x-cms-input` for presentation. The CMS reads only the input structure and retains the original validator for execution.
+
+Studio supports strings, calendar dates, finite numbers, booleans, string arrays, choices, and nested objects. Non-recursive local references are resolved. Ambiguous unions, structural intersections, recursive schemas, and unsupported field shapes fail configuration rather than producing incomplete forms.
+
 ## Start editing
 
-1. Run `pnpm dev` and open `http://localhost:3000/_cms/app`.
+1. Start your Nuxt application and open its `/_cms/app` route. In this repository, `pnpm dev` runs the canonical example at `http://localhost:3000/_cms/app`.
 2. Enter your initialization token and create the first administrator. Initialization then closes.
 3. Create a page in Studio, edit it, and publish it. The module provides page routing and rendering; your app must render `<NuxtPage />` in `app/app.vue` if it has a custom app shell. Existing app routes can provide custom page layouts.
 
@@ -86,14 +162,15 @@ Draft delivery requires the current Studio session and document access permissio
 
 ## Customize
 
-- Define collections with Zod in `documents.collections`. Import `field` from `@phtngyn/cms/DocumentModel` to add field labels and input hints.
+- Define collections with Effect Schema in `documents.collections`. Import `field` from `@phtngyn/cms/DocumentModel` to add field labels and input hints.
 - Use the auto-imported `useDocument` and `useDocumentQuery` composables and `DocumentRenderer`, `DocumentScope`, and `DocumentField` components for custom rendering.
 - Import `defineCmsBlock` from `@phtngyn/cms/Authoring` to declare editable props and slots in your Nuxt Vue components.
 - Optionally provide `initialSources` to import Markdown documents once when the installation is first claimed.
 
-## License
-
-Proprietary. Copyright (c) 2026 Phat (phtngyn). All rights reserved. Use, copying, modification, and redistribution require prior written permission. Third-party components retain their own licenses.
+For a folder of published Markdown files, import `seedFromDirectory` from `@phtngyn/cms/Seed` and set
+`initialSources: seedFromDirectory(new URL('./seed/', import.meta.url))` in `cms.config.ts`.
+The folder is read when Nuxt loads the configuration. Paths within it become document source paths;
+for example, `seed/en/index.md` becomes `en/index.md`. Files are published on the first claim.
 
 ## Studio and authoring during development
 
@@ -113,7 +190,7 @@ A collection can restrict available component blocks:
 pages: {
   label: 'Page',
   route: '/:path*',
-  schema: z.object({ title: z.string() }),
+  schema: Schema.Struct({ title: Schema.String }),
   body: {
     blocks: ['content-hero'],
     groups: ['Editorial'],
@@ -159,3 +236,109 @@ Every list item needs a required `id: string` in its Vue type. Studio generates
 Collaboration merges object fields and list-item fields independently. List ordering is separate from item values; simultaneous insertions at the same position retain both items in deterministic identity order. Removing an item takes precedence over concurrent edits to it. Competing edits to the same field use Yjs conflict resolution. Authoring schemas and controls update through the existing HMR path without reseeding content.
 
 See the example's `ContentSection.vue` for a complete component-local declaration with images, links, layout settings, repeatable features and nested blocks.
+
+## Headless forms
+
+Register a form under the kebab-case name of your Nuxt Vue renderer. `defineCmsForm` is a normal TypeScript helper, not a compiler macro. It declares the question types and validation rules editors may use:
+
+```ts
+import { defineCmsConfig } from '@phtngyn/cms/Configuration'
+import { defineCmsForm } from '@phtngyn/cms/Forms'
+
+// Inside your existing defineCmsConfig configuration:
+forms: {
+  'contact-form': {
+    definition: defineCmsForm({
+      label: 'Contact form',
+      fieldTypes: ['text', 'email', 'textarea', 'number', 'checkbox', 'select'],
+      rules: ['required', 'minLength', 'maxLength', 'min', 'max'],
+    }),
+    onSubmit: async ({ form, values }) => {
+      // Server only: deliver or persist validated answers here.
+      // values are keyed by stable question IDs; form.steps contains their labels.
+    },
+  },
+},
+```
+
+Create `ContactForm.vue` with an optional `cmsForm?: CmsFormDefinition` prop. The registration supplies its Studio authoring controls; do not also declare `defineCmsBlock` for that renderer. Forms appear in the Forms block group and follow collection block permissions. Editors add steps, questions, choices and permitted rules in the property panel. One step produces a single-step form. Question and option IDs are managed by Studio; labels can change without changing identities. Select answers contain option IDs. There is no website input markup or CSS supplied by CMS.
+
+A valid authored form receives `cmsForm` from `DocumentRenderer`. Incomplete drafts do not; show a helpful placeholder until the form is valid. Mount your custom form contents only when that definition exists:
+
+```ts
+import type { CmsFormDefinition } from '@phtngyn/cms/Forms'
+import { useCmsForm } from '@phtngyn/cms/Forms'
+
+const props = defineProps<{ definition: CmsFormDefinition }>()
+const {
+  fields,
+  steps,
+  values,
+  errors,
+  currentStep,
+  stepIndex,
+  isFirstStep,
+  isLastStep,
+  isSubmitting,
+  isSuccess,
+  isPreview,
+  error,
+  next,
+  previous,
+  validate,
+  submit,
+  reset,
+} = useCmsForm(() => props.definition)
+```
+
+The composable accepts a value, ref, or getter and returns destructurable refs and functions. Bind controls to `values[field.id]`. Number answers must be numbers or null, checkbox answers booleans, and other answers strings. Empty optional answers reach the server handler as null; a required checkbox must be checked. `next()` validates the current step, `previous()` preserves answers, and `submit()` validates every step and returns whether submission succeeded. Validation errors are keyed by question ID; `_form` holds a form-wide error. Render accessible labels, error announcements, progress, and focus behavior in your application.
+
+Definition replacements preserve answers for matching IDs and field types within the same form, clear validation state, and cancel pending client requests. `reset()` clears answers and submission state. The composable prevents overlapping submissions and repeat submission after success until reset. Scope disposal cancels client work. Cancellation cannot undo a server handler that has already started. An optional `submit(payload, signal)` transport override supports advanced integrations; it must return `CmsFormResult` and preserve server-side validation.
+
+The endpoint resolves the current published form and checks its exact serialized revision, including capabilities and question settings. Stale pages must reload. Draft preview validates locally without invoking the handler. Invalid structure prevents publication; invalid answers and unknown answer keys never reach the handler. Dynamic editor-created questions have runtime-validated answer types, not compile-time-known answer keys.
+
+Requests are limited to 128 KiB and 60 submissions per minute per server process, shared across forms. Browser requests with a foreign Origin are rejected. For deployments with multiple replicas or stronger spam protection, enforce a shared limit or challenge at your edge. There is no automatic retry, durable deduplication, inbox, email delivery, upload, branching, or save-and-resume in this release. Application handlers should account for retries after an uncertain network outcome. Configuration changes use Nuxt's restart lifecycle.
+
+See `examples/nuxt/app/components/FormContents.vue` for a Tailwind-rendered example. Its server handler acknowledges submissions without storing answers.
+
+## Website languages
+
+Declare languages and developer-owned website strings together in `cms.config.ts`:
+
+```ts
+i18n: {
+  defaultLocale: 'en',
+  fallbackLocale: 'en',
+  prefixDefaultLocale: false,
+  locales: {
+    en: { name: 'English', messages: {
+      navigation: { home: 'Home' },
+      footer: { copyright: '© {year} Acme' },
+    } },
+    de: { name: 'Deutsch', messages: {
+      navigation: { home: 'Startseite' },
+    } },
+  },
+},
+```
+
+Locale codes also define the first directory of document source paths: `en/index.md` serves `/`, and `de/index.md` serves `/de`. Collection source matching starts after that directory. Markdown contains the editor-authored language already; it needs no translation key. Markdown and source paths remain stored in document revisions, with collaborative working edits checkpointed into Markdown. Seed files import once; changing them does not synchronize an existing database.
+
+Use the auto-imported composable in website components:
+
+```ts
+const { t, locale } = useCmsI18n()
+const navigation = computed(() => [{ label: t('navigation.home'), to: locale.value === 'de' ? '/de' : '/' }])
+t('footer.copyright', { year: 2026 })
+useHead({ htmlAttrs: { lang: locale } })
+```
+
+`locale` is a read-only computed value derived from the current URL, including in Studio's website preview. Switch languages by navigating to a localized URL. For documents with different authored slugs, supply their actual destinations. Lists can explicitly pass `locale.value` to `useDocumentQuery`.
+
+Message keys receive generated TypeScript completion. Dictionaries contain nested plain strings; dots are reserved for key paths. Named `{parameters}` accept strings and numbers; missing parameters remain visible. Messages fall back from the URL locale to `fallbackLocale`, then to the key. Omit `fallbackLocale` (or set it to `null`) to disable fallback. The same explicit fallback policy applies to document lookup. Development warns about missing requested-locale messages. Render messages as text, and use native `Intl` for date and number formatting.
+
+Only validated public i18n data enters the website bundle. Installation credentials and handlers stay server-side. Small dictionaries can stay inline; larger ones can be imported into the same config. Configuration changes restart Nuxt. Omitting `i18n` preserves unlocalized source paths; the composable returns an empty locale and untranslated keys.
+
+## License
+
+Proprietary. Copyright (c) 2026 Phat (phtngyn). All rights reserved. Use, copying, modification, and redistribution require prior written permission. Third-party components retain their own licenses.

package/package.json

@@ -14,7 +14,7 @@
     "directory": "packages/nuxt"
   },
   "name": "@phtngyn/cms",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "type": "module",
   "files": [
     "studio",
@@ -38,38 +38,53 @@
     "./DocumentModel": {
       "types": "./src/DocumentModel.d.ts",
       "import": "./src/DocumentModel.js"
+    },
+    "./Seed": {
+      "types": "./src/Seed.d.ts",
+      "import": "./src/Seed.js"
+    },
+    "./I18n": {
+      "types": "./src/I18n.d.ts",
+      "import": "./src/I18n.js"
+    },
+    "./Forms": {
+      "types": "./src/Forms.d.ts",
+      "import": "./src/Forms.js"
     }
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1127.0",
-    "@comark/nuxt": "^0.6.2",
-    "@comark/vue": "^0.6.2",
-    "@effect/platform-node-shared": "^4.0.0-rc.112",
-    "@effect/sql-pg": "^4.0.0-rc.112",
-    "@hocuspocus/server": "^4.6.0",
+    "@aws-sdk/client-s3": "^3.1131.0",
+    "@comark/nuxt": "^0.7.0",
+    "@comark/vue": "^0.7.0",
+    "@effect/platform-node-shared": "^4.0.0-rc.115",
+    "@effect/sql-pg": "^4.0.0-rc.115",
+    "@hocuspocus/server": "^4.7.0",
     "@nuxt/kit": "^4.5.2",
     "@nuxt/schema": "^4.5.2",
+    "@nuxtjs/robots": "^6.2.2",
+    "@nuxtjs/sitemap": "^8.5.1",
     "@tiptap/core": "^3.31.3",
     "@tiptap/starter-kit": "^3.31.3",
     "@tiptap/y-tiptap": "^3.0.9",
-    "@vue/compiler-sfc": "^3.6.0-rc.7",
-    "better-auth": "^1.7.3",
-    "comark": "^0.6.2",
+    "@vue/compiler-sfc": "^3.6.0-rc.8",
+    "better-auth": "^1.7.4",
+    "comark": "^0.7.0",
     "diff": "^9.0.0",
     "drizzle-orm": "^1.0.0-rc.5-169397b",
-    "effect": "^4.0.0-rc.112",
+    "effect": "^4.0.0-rc.115",
     "h3": "^1.15.11",
     "jiti": "^2.7.0",
     "nitropack": "^2.13.4",
+    "nuxt-schema-org": "^6.3.1",
+    "nuxt-seo-utils": "^8.5.0",
     "pg": "^8.23.0",
     "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
-    "vite": "^8.2.2",
+    "vite": "^8.3.0",
     "vue-component-meta": "^3.3.11",
-    "yjs": "^13.6.32",
-    "zod": "^4.5.4"
+    "yjs": "^13.6.32"
   },
   "peerDependencies": {
     "nuxt": ">=4.5.0 <5.0.0",
     "vue": ">=3.6.0-rc.6 <4.0.0"
   }
-}
+}

package/src/Configuration-Br7tE9Qt.d.ts

@@ -0,0 +1,68 @@
+import { t as CmsI18nOptions } from "./I18n-DZK4CkJF.js";
+import { n as FormDefinition, s as FormValues, t as FormCapabilities } from "./Forms-BsJMev5_.js";
+import { i as CmsDocumentModelOptions } from "./DocumentModel-BB9igGC7.js";
+import { r as SeoConfiguration } from "./Seo-402YumpT.js";
+import { Cause, Context, Crypto, DateTime, Effect, Layer, Option, Result, Schema, Scope, Stream } from "effect";
+import { Extension, Node } from "@tiptap/core";
+import "comark";
+//#region ../../node_modules/.pnpm/prosemirror-view@1.42.3/node_modules/prosemirror-view/dist/index.d.ts
+declare global {
+  interface Node {}
+}
+//#endregion
+//#region ../server/src/Forms.d.ts
+type FormSubmissionHandler = (submission: {
+  readonly form: FormDefinition;
+  readonly values: FormValues;
+}) => void | PromiseLike<void>;
+//#endregion
+//#region src/Configuration.d.ts
+type CmsSeoOptions = Schema.Codec.Encoded<typeof SeoConfiguration>;
+interface CmsInitialDocument {
+  readonly markdown: string;
+  readonly published: boolean;
+  readonly sourcePath: string;
+}
+type CmsInitialDocumentProvider = () => PromiseLike<ReadonlyArray<CmsInitialDocument>> | ReadonlyArray<CmsInitialDocument>;
+interface CmsCleanupOptions {
+  readonly initialDelayMillis?: number;
+  readonly intervalMillis?: number;
+}
+interface CmsMediaStorageCredentials {
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  readonly sessionToken?: string;
+}
+interface CmsMediaStorageOptions {
+  readonly bucket: string;
+  readonly credentials?: CmsMediaStorageCredentials;
+  readonly endpoint?: string;
+  readonly forcePathStyle?: boolean;
+  readonly provisionBucket?: boolean;
+  readonly region: string;
+}
+interface CmsMediaOptions {
+  readonly maxUploadBytes?: number;
+  readonly publicBaseUrl: string;
+  readonly storage: CmsMediaStorageOptions;
+}
+interface CmsConfiguration {
+  readonly forms?: Readonly<Record<string, {
+    readonly definition: FormCapabilities;
+    readonly onSubmit: FormSubmissionHandler;
+  }>>;
+  readonly baseUrl: string;
+  readonly cleanup?: false | CmsCleanupOptions;
+  readonly databaseUrl: string;
+  readonly documents: CmsDocumentModelOptions;
+  readonly i18n?: CmsI18nOptions;
+  readonly initialSources?: CmsInitialDocumentProvider;
+  readonly initializationToken: string;
+  readonly media?: false | CmsMediaOptions;
+  readonly seo?: CmsSeoOptions;
+  readonly secret: string;
+}
+declare function defineCmsConfig<const Configuration extends CmsConfiguration>(configuration: Configuration): Configuration;
+//#endregion
+export { CmsMediaOptions as a, CmsSeoOptions as c, CmsInitialDocumentProvider as i, defineCmsConfig as l, CmsConfiguration as n, CmsMediaStorageCredentials as o, CmsInitialDocument as r, CmsMediaStorageOptions as s, CmsCleanupOptions as t };
+//# sourceMappingURL=Configuration-Br7tE9Qt.d.ts.map