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

package/README.md

@@ -76,7 +76,13 @@ For storage using the AWS credential chain, omit `credentials`. To create a miss
 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.
 
-Studio is bundled with the module; no separate Studio deployment or auth setup is required. Readiness is available at `/_cms/health/ready`. Restart Nuxt after changing CMS configuration or component schemas.
+Studio is bundled with the module; no separate Studio deployment or auth setup is required. Readiness is available at `/_cms/health/ready`. Component schemas update through HMR during development. CMS configuration changes use Nuxt’s restart lifecycle.
+
+## Preview drafts
+
+Studio previews render authored documents through the same Nuxt routes, layouts, components, `useDocument`, and `useDocumentQuery` used by the website. A page can be previewed before its first publication. Preview mode follows internal navigation and survives iframe reloads; ordinary website requests continue to read published content.
+
+Draft delivery requires the current Studio session and document access permission. Preview URLs contain only iframe coordination information, never an access token. Preview HTML and draft API responses are private and uncached. Once the page renders, the editor bridge overlays current collaborative edits without waiting for publication or replacing Nuxt HMR.
 
 ## Customize
 
@@ -88,3 +94,68 @@ Studio is bundled with the module; no separate Studio deployment or auth setup i
 ## 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.
+
+## Studio and authoring during development
+
+Studio at `/_cms/app` is a separate HTML document, Vue application, and Tailwind build. It owns its Nuxt UI settings, styles, and overlays independently of the website. Your app root and layouts apply only to the website. Both applications use the same Nuxt server; no separate Studio server or port is required.
+
+Only components that declare `defineCmsBlock` appear in the authoring catalog. Nuxt compiles their Vue props, slots, imported types, and presentation into one generated `#cms/authoring` module. Studio’s entry imports this module through Nuxt’s Vite graph, so isolation does not require a custom HMR transport. A separate Vue component map supplies Comark’s renderer, so adding or removing a block does not reinitialize Studio. Valid semantic changes update Studio and rebuild the Nitro worker automatically, keeping the development listener running. Invalid changes show a Vite error and retain the last valid catalog.
+
+An open editor reads the new catalog without reseeding content or replacing its collaborative document. Publishing waits until the collaboration server and editor use the same catalog revision. Installation configuration changes still use Nuxt’s configuration restart lifecycle.
+
+## Component authoring and collection permissions
+
+Keep the Vue props, slots, defaults, and `defineCmsBlock` declaration together in the component's `<script setup lang="ts">`. Only declared fields and regions appear in Studio. Text regions accept plain text; rich-text regions offer only their declared `features`. Optional slots can be removed and added again. Initial content seeds new blocks; it never overwrites existing content when a declaration changes. Render optional slot wrappers conditionally to avoid empty layout space.
+
+A collection can restrict available component blocks:
+
+```ts
+pages: {
+  label: 'Page',
+  route: '/:path*',
+  schema: z.object({ title: z.string() }),
+  body: {
+    blocks: ['content-hero'],
+    groups: ['Editorial'],
+  },
+},
+```
+
+Block names and groups form a union. Omitting `body` permits all declared blocks; `body: {}` permits none. Ordinary text remains available. Unknown selectors fail configuration validation. Studio insertion and server publication use the same document-owned rules, including blocks inside other content. A restriction change preserves existing content and reports what must be corrected before publication.
+
+Clearing an optional property removes its stored override, so a Vue default can apply. Reset writes the current declared default. Nullable fields also offer an explicit no-value choice; empty strings, zero, and false remain actual values.
+
+### Images, links, and composition
+
+String props can declare `input: 'image'` or `input: 'link'`. Studio uses the existing media library for image selection/upload and the document catalog for page links. Values remain ordinary URL strings: internal links store the selected document's public path. Image descriptions belong to a separate Vue prop; Studio does not invent an alt-text field or change your component's rendering. URL syntax and allowed schemes are checked before publication, and semantic props participate in the existing document/media reference index, including inside objects and lists. Changing a target's public path requires updating its links; references do not silently retarget by title.
+
+Slots with `input: 'blocks'` accept nested components. Optional `blocks` and `groups` selectors restrict direct children; omitting both permits all collection-allowed blocks. Collection permissions apply at every depth. Studio offers insertion, selection, deletion and sibling reordering inside each region. Existing content is retained when a schema change makes it invalid.
+
+Use object props for structured data and slots for composed content:
+
+```ts
+interface Props {
+  settings?: { compact: boolean }
+  features?: Array<{ id: string; title: string; link?: string }>
+}
+// Inside the component's defineCmsBlock declaration:
+props: {
+  settings: {
+    label: 'Settings', input: 'object',
+    fields: { compact: { label: 'Compact spacing', input: 'toggle' } },
+  },
+  features: {
+    label: 'Features', input: 'list',
+    fields: {
+      title: { label: 'Title', input: 'text' },
+      link: { label: 'Link', input: 'link' },
+    },
+  },
+},
+```
+
+Every list item needs a required `id: string` in its Vue type. Studio generates and preserves this value; use it as the item's Vue `:key`. Do not declare an editable control for `id`. Object/list shapes, requiredness and string choices come from Vue, including nested fields. Literal factory defaults such as `() => []` and `() => ({ compact: false })` are supported. Computed defaults and recursive types are not editable contracts.
+
+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.

package/package.json

@@ -14,10 +14,10 @@
     "directory": "packages/nuxt"
   },
   "name": "@phtngyn/cms",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.1",
   "type": "module",
   "files": [
-    "dist",
+    "studio",
     "src",
     "README.md",
     "LICENSE"
@@ -61,9 +61,9 @@
     "h3": "^1.15.11",
     "jiti": "^2.7.0",
     "nitropack": "^2.13.4",
-    "nuxt-component-meta": "^0.18.0",
     "pg": "^8.23.0",
-    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.15.tsgo.7.0.2",
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
+    "vite": "^8.2.2",
     "vue-component-meta": "^3.3.11",
     "yjs": "^13.6.32",
     "zod": "^4.5.4"
@@ -72,4 +72,4 @@
     "nuxt": ">=4.5.0 <5.0.0",
     "vue": ">=3.6.0-rc.6 <4.0.0"
   }
-}
+}

package/src/Authoring.d.ts

@@ -4,18 +4,30 @@ export type CmsBlockProp<Value> = {
   readonly label: string;
   readonly help?: string;
 } & ([NonNullable<Value>] extends [never] ? never : [NonNullable<Value>] extends [string] ? {
-  readonly input: 'text' | 'textarea' | 'select';
+  readonly input: 'text' | 'textarea' | 'select' | 'image' | 'link';
   readonly optionLabels?: Partial<Record<Extract<Value, string>, string>>;
 } : [NonNullable<Value>] extends [number] ? {
   readonly input: 'number';
 } : [NonNullable<Value>] extends [boolean] ? {
   readonly input: 'toggle';
+} : [NonNullable<Value>] extends [ReadonlyArray<infer Item>] ? Item extends {
+  readonly id: string;
+} ? {
+  readonly input: 'list';
+  readonly fields: { readonly [Key in Exclude<keyof Item, 'id'>]?: CmsBlockProp<Item[Key]>; };
+} : never : [NonNullable<Value>] extends [object] ? {
+  readonly input: 'object';
+  readonly fields: { readonly [Key in keyof NonNullable<Value>]?: CmsBlockProp<NonNullable<Value>[Key]>; };
 } : never);
 export type CmsBlockSlot = {
   readonly label: string;
   readonly help?: string;
 } & ({
   readonly input: 'text';
+} | {
+  readonly input: 'blocks';
+  readonly blocks?: ReadonlyArray<string>;
+  readonly groups?: ReadonlyArray<string>;
 } | {
   readonly input: 'rich-text';
   readonly features: ReadonlyArray<'bold' | 'italic' | 'link' | 'bullet-list' | 'code'>;