camox 0.0.0 → 0.1.2-alpha.2

package/skills/camox-block/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: camox-block
+description: "How to create Camox block definition files. Use this skill whenever the user wants to create a new block for their Camox website, add a page section/component, build a reusable content block, or asks about the block definition API. Trigger on mentions of blocks, sections, page components, content types, or any request to add new visual sections to a Camox site — even if they don't say 'block' explicitly."
+---
+
+# Creating Camox Block Definitions
+
+A block is a reusable page section (hero, testimonial, gallery, footer...). Users compose pages by assembling blocks. This skill covers creating block **definitions** — the template that describes a block's schema and rendering. Not the content (an instance of a block).
+
+## Quick Start
+
+A block file lives in the app's `src/camox/blocks/` folder, is a `.tsx` file, and exports `block`:
+
+```tsx
+import { Type, createBlock } from "camox/createBlock";
+
+const myBlock = createBlock({
+  id: "my-block", // Must match filename (kebab-case)
+  title: "My Block", // Human-readable name
+  description: "...", // Tells the AI when/how to use this block
+  toMarkdown: ["# {{title}}", "{{description}}"], // Markdown template
+  content: {
+    /* ... */
+  }, // Editable content schema
+  settings: {
+    /* ... */
+  }, // Optional config toggles
+  component: MyBlockComponent,
+});
+
+function MyBlockComponent() {
+  return (
+    <section>
+      <myBlock.Field name="title">{(content) => <h1>{content}</h1>}</myBlock.Field>
+    </section>
+  );
+}
+
+export { myBlock as block };
+```
+
+## The `createBlock` options
+
+| Option        | Required | Description                                                                                                                                                                                                   |
+| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`          | yes      | Unique kebab-case identifier. Must match the filename without extension.                                                                                                                                      |
+| `title`       | yes      | Display name shown in the CMS UI.                                                                                                                                                                             |
+| `description` | yes      | Tells the AI assistant when to use this block and what content it expects. Write it like guidance for an LLM — be specific about placement, tone, and content guidelines.                                     |
+| `toMarkdown`  | yes      | A `string[]` template for rendering block content as markdown. Each line is joined with `\n\n`. Use `{{fieldName}}` placeholders for field values. Lines where all placeholders resolve to empty are omitted. |
+| `content`     | yes      | An object where each key is a field name and each value is a `Type.*` call. These fields are inline-editable in the CMS.                                                                                      |
+| `settings`    | no       | Same shape as `content`, but for configuration that lives in a settings panel (not inline). Only `Type.Enum` and `Type.Boolean` should be used here.                                                          |
+| `layoutOnly`  | no       | If `true`, the block won't appear in the "add block" sheet — it can only be placed inside layouts (e.g. navbar, footer).                                                                                      |
+| `component`   | yes      | A named React function component that renders the block.                                                                                                                                                      |
+
+## Markdown Template (`toMarkdown`)
+
+The `toMarkdown` array controls how block content is rendered as markdown for AI features (summaries, SEO). Each string in the array becomes a paragraph (joined with `\n\n`). Use `{{fieldName}}` placeholders that reference keys in `content`.
+
+**Field resolution rules:**
+
+- **String**: raw text value
+- **Link**: `[text](href)`
+- **Image**: `![alt](filename)`
+- **File**: `[filename](url)`
+- **Embed**: raw URL string
+- **RepeatableObject**: each item rendered via its own `toMarkdown` (if set on the RepeatableObject options), items joined with `\n\n`
+- **Boolean/Enum**: raw string value
+
+Lines where ALL placeholders resolve to empty are omitted from output.
+
+**Examples:**
+
+```tsx
+// Hero block
+createBlock({
+  toMarkdown: ["# {{title}}", "{{description}}", "{{illustration}}", "{{cta}}"],
+  content: { ... },
+})
+
+// Testimonial — combine fields on one line
+createBlock({
+  toMarkdown: ["> {{quote}}", "— {{author}}, {{title}}, {{company}}"],
+  content: { ... },
+})
+
+// Statistics — RepeatableObject with its own toMarkdown
+createBlock({
+  toMarkdown: ["## {{subtitle}}", "{{description}}", "{{statistics}}"],
+  content: {
+    subtitle: Type.String({ default: "..." }),
+    description: Type.String({ default: "..." }),
+    statistics: Type.RepeatableObject(
+      {
+        number: Type.String({ default: "100M+" }),
+        label: Type.String({ default: "pages served" }),
+      },
+      { minItems: 4, maxItems: 8, toMarkdown: ["**{{number}}** — {{label}}"] }
+    ),
+  },
+})
+```
+
+The template is type-safe — `{{fieldName}}` placeholders are validated against the content keys at compile time. Typos like `{{titl}}` produce a TypeScript error.
+
+## Content Field Types
+
+Import `Type` from `"camox/createBlock"`. Every field requires a default value.
+
+### Type.String
+
+Inline-editable text. The workhorse field type.
+
+```tsx
+Type.String({
+  default: "Hello world", // Required
+  title: "Heading", // Optional label
+  maxLength: 280, // Optional
+  minLength: 1, // Optional
+  pattern: "^[A-Z]", // Optional regex
+});
+```
+
+### Type.Boolean
+
+A toggle. Use in `settings` for config, or in `content` for user-controlled flags.
+
+```tsx
+Type.Boolean({ default: false, title: "Show background" });
+```
+
+### Type.Enum
+
+A dropdown with predefined options. Most commonly used in `settings`.
+
+```tsx
+Type.Enum({
+  default: "left",
+  options: { left: "Left", center: "Center", right: "Right" },
+  title: "Alignment",
+});
+```
+
+The `default` must be one of the keys in `options`.
+
+### Type.Link
+
+A link with text, URL (or internal page reference), and new-tab toggle.
+
+```tsx
+Type.Link({
+  default: { text: "Learn more", href: "/", newTab: false },
+  title: "CTA",
+});
+```
+
+### Type.Image
+
+A single image, or a repeatable array of images.
+
+```tsx
+// Single image
+Type.Image({ title: "Cover photo" });
+
+// Multiple images (creates a repeatable list)
+Type.Image({ multiple: true, defaultItems: 6, title: "Gallery images" });
+```
+
+### Type.File
+
+A file upload, with MIME type filtering.
+
+```tsx
+Type.File({
+  accept: ["application/pdf"],
+  title: "PDF Document",
+});
+
+// Multiple files
+Type.File({
+  accept: ["application/pdf"],
+  multiple: true,
+  defaultItems: 0,
+  title: "Documents",
+});
+```
+
+### Type.Embed
+
+A URL validated against a regex pattern. Used for embedding external content.
+
+```tsx
+Type.Embed({
+  pattern: "https:\\/\\/(www\\.)?(youtube\\.com|youtu\\.be)\\/.+",
+  default: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+  title: "YouTube URL",
+});
+```
+
+The `default` must match the `pattern` — an error is thrown at definition time otherwise.
+
+### Type.RepeatableObject
+
+An array of structured items. Each item is an object with its own fields. This is how you create lists of things (testimonials, features, stats, links...).
+
+```tsx
+Type.RepeatableObject(
+  {
+    name: Type.String({ default: "Feature" }),
+    description: Type.String({ default: "Description" }),
+  },
+  {
+    minItems: 1, // Must be >= 1
+    maxItems: 10,
+    title: "Features",
+    toMarkdown: ["### {{name}}", "{{description}}"], // Optional markdown template for each item
+  },
+);
+```
+
+The `toMarkdown` option on RepeatableObject defines how each item is rendered as markdown when the parent block's `toMarkdown` references this field. If omitted, fields are joined with " — " as a fallback.
+
+RepeatableObjects can be nested — an item can contain another RepeatableObject:
+
+```tsx
+columns: Type.RepeatableObject(
+  {
+    title: Type.String({ default: "Column" }),
+    links: Type.RepeatableObject(
+      {
+        link: Type.Link({ default: { text: "Link", href: "#", newTab: false } }),
+      },
+      { minItems: 1, maxItems: 999, toMarkdown: ["{{link}}"] },
+    ),
+  },
+  { minItems: 2, maxItems: 4, title: "Columns", toMarkdown: ["### {{title}}", "{{links}}"] },
+);
+```
+
+## Rendering in the Component
+
+The component is a regular React function. It uses methods on the block constant to render each field. The pattern is always: use the appropriate renderer for each field type, with a render-prop child that receives the field value.
+
+### Rendering String fields — `block.Field`
+
+```tsx
+<myBlock.Field name="title">{(content) => <h1>{content}</h1>}</myBlock.Field>
+```
+
+The `name` must match a key in `content` that is a `Type.String`. The `content` argument is a string. This is what makes the field inline-editable in the CMS.
+
+### Rendering Link fields — `block.Link`
+
+Inside the render prop, use the `Link` component from `@tanstack/react-router` instead of a plain `<a>` tag. This enables client-side navigation for internal links.
+
+```tsx
+import { Link } from "@tanstack/react-router";
+
+<myBlock.Link name="cta">
+  {({ text, href, newTab }) => (
+    <Link to={href} target={newTab ? "_blank" : undefined} rel={newTab ? "noreferrer" : undefined}>
+      {text}
+    </Link>
+  )}
+</myBlock.Link>;
+```
+
+### Rendering Image fields — `block.Image`
+
+```tsx
+<myBlock.Image name="cover">{(img) => <img src={img.url} alt={img.alt} />}</myBlock.Image>
+```
+
+### Rendering File fields — `block.File`
+
+```tsx
+<myBlock.File name="document">
+  {(file) => (
+    <a href={file.url} download={file.filename}>
+      Download
+    </a>
+  )}
+</myBlock.File>
+```
+
+### Rendering Embed fields — `block.Embed`
+
+```tsx
+<myBlock.Embed name="videoUrl">{(url) => <iframe src={url} />}</myBlock.Embed>
+```
+
+### Rendering RepeatableObject fields — `block.Repeater`
+
+```tsx
+<myBlock.Repeater name="features">
+  {(item) => (
+    <div>
+      <item.Field name="name">{(content) => <h3>{content}</h3>}</item.Field>
+      <item.Field name="description">{(content) => <p>{content}</p>}</item.Field>
+    </div>
+  )}
+</myBlock.Repeater>
+```
+
+Inside a Repeater, the `item` callback argument exposes the same `.Field`, `.Link`, `.Image`, `.File`, `.Embed`, and `.Repeater` methods — scoped to that item. This is how nested repeaters work too:
+
+```tsx
+<footer.Repeater name="columns">
+  {(column) => (
+    <column.Repeater name="links">
+      {(linkItem) => (
+        <linkItem.Link name="link">{({ text, href }) => <a href={href}>{text}</a>}</linkItem.Link>
+      )}
+    </column.Repeater>
+  )}
+</footer.Repeater>
+```
+
+For `Type.Image({ multiple: true })`, the repeater item has a single `image` key:
+
+```tsx
+<gallery.Repeater name="images">
+  {(item) => <item.Image name="image">{(img) => <img src={img.url} alt={img.alt} />}</item.Image>}
+</gallery.Repeater>
+```
+
+### Reading settings — `block.useSetting`
+
+```tsx
+function MyComponent() {
+  const theme = myBlock.useSetting("theme");
+  const compact = myBlock.useSetting("compact");
+  // Use these values in your JSX for conditional rendering/styling
+}
+```
+
+### Detached rendering — `block.Detached`
+
+Renders content outside the block's DOM container. Useful for fixed/floating elements like sticky navbars or modals.
+
+```tsx
+<myBlock.Detached>
+  <div className="fixed top-0 left-0 right-0 z-50">{/* floating content */}</div>
+</myBlock.Detached>
+```
+
+## Rules and Conventions
+
+1. **File = one block.** One `.tsx` file per block in `src/camox/blocks/`. The `id` must match the filename (without `.tsx`).
+2. **Named export as `block`.** Always: `export { myVar as block }`. Not a default export.
+3. **Named function component.** Use `function MyComponent()`, not an arrow function. Reference it in `createBlock` before its declaration is fine (hoisting).
+4. **All fields need defaults.** Every `Type.*` call requires a default value (images and files get automatic placeholders).
+5. **Description is for the AI.** Write the `description` as guidance for an LLM — explain when to use this block, what kind of content it's for, and where it fits on a page.
+6. **`toMarkdown` is required.** Every block must define how its content renders as markdown. Use `{{fieldName}}` placeholders matching content keys.
+7. **Settings = Enum and Boolean only.** Keep settings simple. Use `content` for everything the user edits inline.
+8. **RepeatableObject minItems >= 1.** You can't have an empty repeatable — there's always at least one item.
+9. **Import path is `"camox/createBlock"`.** Both `Type` and `createBlock` come from this import.
+10. **Use Tailwind CSS for styling.** All example blocks use Tailwind utility classes. Follow the same patterns: `container mx-auto px-4` for centered content, responsive breakpoints, etc.

package/skills/camox-layout/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: camox-layout
+description: "How to create and edit Camox layout definition files. Use this skill whenever the user wants to create a new layout for their Camox website, modify an existing layout, wrap pages in shared structure (navbar + footer), customize meta titles or OG images, or asks about the layout definition API. Trigger on mentions of layouts, page wrappers, page templates, shared page structure, navbar/footer placement, or any request to define how pages are structured — even if they don't say 'layout' explicitly."
+---
+
+# Creating Camox Layout Definitions
+
+A layout wraps pages in shared structure — a navbar at the top, a footer at the bottom, consistent styling. Each page in the CMS is assigned a layout. This skill covers creating layout **definitions** — the template that describes which blocks surround page content and how to render them.
+
+## Quick Start
+
+A layout file lives in the app's `src/camox/layouts/` folder, is a `.tsx` file, and exports `layout`:
+
+```tsx
+import { createLayout } from "camox/createLayout";
+import { block as navbarBlock } from "../blocks/navbar";
+import { block as footerBlock } from "../blocks/footer";
+
+const myLayout = createLayout({
+  id: "my-layout", // Must match filename (kebab-case)
+  title: "My Layout", // Human-readable name
+  description: "When to use this layout",
+  blocks: {
+    before: [navbarBlock], // Blocks rendered before page content
+    after: [footerBlock], // Blocks rendered after page content
+  },
+  component: MyLayoutComponent,
+  buildMetaTitle: ({ pageMetaTitle, projectName }) => `${pageMetaTitle} | ${projectName}`,
+});
+
+function MyLayoutComponent({ children }: { children: React.ReactNode }) {
+  return (
+    <main className="flex min-h-screen flex-col">
+      <myLayout.blocks.Navbar />
+      <div className="flex-1">{children}</div>
+      <myLayout.blocks.Footer />
+    </main>
+  );
+}
+
+export { myLayout as layout };
+```
+
+## The `createLayout` options
+
+| Option           | Required | Description                                                                                                                                                                                 |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`             | yes      | Unique kebab-case identifier. Must match the filename without extension.                                                                                                                    |
+| `title`          | yes      | Display name shown in the CMS UI.                                                                                                                                                           |
+| `description`    | yes      | Tells the CMS user (or AI agent) when to pick this layout. Write it as guidance — explain what kind of pages this layout suits.                                                             |
+| `blocks`         | yes      | An object with `before` and `after` arrays. Each array contains block instances (imported from block files). `before` blocks render above the page content, `after` blocks render below it. |
+| `component`      | yes      | A named React function component that renders the layout shell. Receives `{ children }` — the page content.                                                                                 |
+| `buildMetaTitle` | yes      | A function that builds the `<title>` tag. Receives `{ pageMetaTitle, projectName, pageFullPath }` and returns a string.                                                                     |
+| `buildOgImage`   | no       | A function that returns a JSX element for generating Open Graph images. Receives `{ title, description, projectName }`.                                                                     |
+
+## Block Placement — `before` and `after`
+
+Layout blocks are split into two groups:
+
+- **`before`**: rendered above the page content (navbars, banners, announcements)
+- **`after`**: rendered below the page content (footers, cookie bars)
+
+The blocks you reference here are regular block definitions (created with `createBlock`). They're typically marked with `layoutOnly: true` in their block definition so they don't appear in the "add block" picker for page content.
+
+```tsx
+blocks: {
+  before: [navbarBlock, announcementBlock],
+  after: [footerBlock],
+}
+```
+
+You can have multiple blocks in either group, or leave one empty:
+
+```tsx
+blocks: {
+  before: [navbarBlock],
+  after: [],  // No blocks after page content
+}
+```
+
+## The Layout Component
+
+The component is a named React function that receives `{ children }` and renders the overall page structure. Inside it, use the slot components from the layout constant to place each block.
+
+Slot components are accessed via `layoutVar.blocks.PascalCaseName`, where the name is the PascalCase version of the block's `id`. For example, a block with `id: "navbar"` becomes `layoutVar.blocks.Navbar`; `id: "cookie-bar"` becomes `layoutVar.blocks.CookieBar`.
+
+```tsx
+function MyLayoutComponent({ children }: { children: React.ReactNode }) {
+  return (
+    <main className="flex min-h-screen flex-col">
+      <myLayout.blocks.Navbar />
+      <div className="flex-1">{children}</div>
+      <myLayout.blocks.Footer />
+    </main>
+  );
+}
+```
+
+The component controls the HTML structure — you decide how to wrap and position the blocks and page content. Use Tailwind CSS for styling.
+
+## Meta Title — `buildMetaTitle`
+
+Controls how the browser tab title is built. Receives three parameters:
+
+- `pageMetaTitle` — the title set on the individual page
+- `projectName` — the site/project name
+- `pageFullPath` — the full URL path of the page
+
+Common patterns:
+
+```tsx
+// "Page Title | Site Name" (most common for content pages)
+buildMetaTitle: ({ pageMetaTitle, projectName }) =>
+  `${pageMetaTitle} | ${projectName}`,
+
+// "Site Name | Page Title" (common for landing/home pages)
+buildMetaTitle: ({ pageMetaTitle, projectName }) =>
+  `${projectName} | ${pageMetaTitle}`,
+
+// Just the page title
+buildMetaTitle: ({ pageMetaTitle }) => pageMetaTitle,
+```
+
+## OG Image — `buildOgImage` (optional)
+
+Generates an Open Graph image (the preview shown when sharing links on social media). The function returns a JSX element that gets rendered as a 1200x630 image.
+
+The JSX here uses **inline styles only** (no Tailwind) because it's rendered by an image generation engine, not a browser. Use `display: "flex"` for layout.
+
+```tsx
+buildOgImage: ({ title, description, projectName }) => (
+  <div
+    style={{
+      display: "flex",
+      flexDirection: "column",
+      justifyContent: "center",
+      alignItems: "flex-start",
+      width: "100%",
+      height: "100%",
+      backgroundColor: "#09090b",
+      padding: "60px 80px",
+      fontFamily: "sans-serif",
+    }}
+  >
+    {projectName && (
+      <div style={{ fontSize: 24, color: "#a1a1aa", marginBottom: 24 }}>
+        {projectName}
+      </div>
+    )}
+    <div
+      style={{
+        fontSize: 64,
+        fontWeight: 700,
+        color: "#fafafa",
+        lineHeight: 1.2,
+        marginBottom: 24,
+      }}
+    >
+      {title}
+    </div>
+    {description && (
+      <div style={{ fontSize: 28, color: "#a1a1aa", lineHeight: 1.5 }}>
+        {description}
+      </div>
+    )}
+  </div>
+),
+```
+
+## Rules and Conventions
+
+1. **File = one layout.** One `.tsx` file per layout in `src/camox/layouts/`. The `id` must match the filename (without `.tsx`).
+2. **Named export as `layout`.** Always: `export { myVar as layout }`. Not a default export.
+3. **Named function component.** Use `function MyComponent()`, not an arrow function. Reference it in `createLayout` before its declaration is fine (hoisting).
+4. **Import path is `"camox/createLayout"`.** The `createLayout` function comes from this import.
+5. **Import blocks from `"../blocks/filename"`.** Layout blocks are imported from the blocks directory. Import the named `block` export.
+6. **Use Tailwind CSS for the component.** Style the layout shell with Tailwind utility classes. The OG image function uses inline styles instead.
+7. **Slot names are PascalCase.** A block with `id: "my-block"` becomes `layout.blocks.MyBlock`.
+8. **`buildMetaTitle` is required.** Every layout must define how page titles are constructed.
+9. **Description guides layout selection.** Write the `description` to help CMS users choose the right layout for their page — explain what types of pages it's suited for.
+10. **Layout blocks should use `layoutOnly: true`.** Blocks intended only for layouts (navbars, footers) should set `layoutOnly: true` in their block definition so they don't clutter the page block picker.

package/index.js

@@ -1,3 +0,0 @@
-module.exports = {
-  hello: () => "Hello, world!",
-};