@407dev/cms-astro 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @407dev/cms-astro
+
+## Purpose
+
+- Astro SDK & integration providing declarative field helpers (`f.text`, `f.img`, `f.richText`, `f.scope`, `f.entryScope`, `f.group`, `f.entries`), ProseMirror `<RichText>` rendering, build-time bundle hydration, preview bridge protocol injection, token-gated draft preview overlays, and an in-browser dev toolbar app for live editing during local development with zero drift.
+
+## Surface
+
+- Declarative field helpers & scopes: [src/fields/index.ts](src/fields/index.ts) (`f`, `f.text`, `f.img`, `f.video`, `f.richText`, `f.number`, `f.toggle`, `f.select`, `f.videoList`, `f.geoArea`, `f.addressList`, `f.scope`, `f.entryScope`, `f.group`, `defineCollection`, `collectionPaths`)
+- Collection factories (`@407dev/cms-astro/collections`): [src/fields/collections.ts](src/fields/collections.ts) (`defineEmailCampaignCollection`, `defineSmsCampaignCollection`)
+- Dynamic dual-callable helper generator derived from `@407dev/field-types`: [src/fields/helpers.ts](src/fields/helpers.ts)
+- Scope & key prefixing: [src/fields/scope.ts](src/fields/scope.ts)
+- Entry scoping: [src/fields/entryScope.ts](src/fields/entryScope.ts) (`f.entryScope`)
+- Group definition & accessor binding: [src/fields/group.ts](src/fields/group.ts)
+- Collection handle & routing: [src/fields/collection.ts](src/fields/collection.ts)
+- ProseMirror RichText renderer: [src/RichText.astro](src/RichText.astro) & [src/richtext/render.ts](src/richtext/render.ts)
+- Preview bridge script generator: [src/preview/bridge-script.ts](src/preview/bridge-script.ts)
+- Dev toolbar app & UI: [src/toolbar/app.ts](src/toolbar/app.ts) & [src/toolbar/widgets.ts](src/toolbar/widgets.ts)
+- Dev config & credential gate: [src/dev/config.ts](src/dev/config.ts) & [src/dev/token.ts](src/dev/token.ts)
+- Dev API routes middleware: [src/dev/routes.ts](src/dev/routes.ts)
+- Dev AST verifier service: [src/dev/verifier.ts](src/dev/verifier.ts)
+- Runtime bundle store & AsyncLocalStorage overlay: [src/runtime/store.ts](src/runtime/store.ts) (`getActiveBundle`, `runWithDraftBundle`, `setBuildBundle`)
+- Client factory & bundle fetcher: [src/client.ts](src/client.ts) (`createCmsClient`, `initCmsClient`, `getClient`)
+- Image transforms & srcset: [src/image.ts](src/image.ts)
+- Head & SEO tag builder: [src/head.ts](src/head.ts)
+- Static site file generators: [src/siteFiles.ts](src/siteFiles.ts) (`renderRedirectsFile`, `renderRobotsTxt`, `renderSitemapXml`)
+- Preview middleware & draft bundle retrieval: [src/middleware/preview.ts](src/middleware/preview.ts) & [src/preview.ts](src/preview.ts)
+- Astro integration definition: [src/integration.ts](src/integration.ts) (`cmsAstro`, `cms`)
+- Package entrypoint: [src/index.ts](src/index.ts)
+
+## Patterns
+
+- **Usage is the Schema**: Reading `f.text('home.hero.heading')` or `<f.text k="home.hero.heading" />` simultaneously marks the DOM editable region and defines the manifest entry for static extraction.
+- **Dual-Callable Helpers**: Helpers work synchronously as functions (`f.text('key', { defaultValue: '...' })`) returning typed primitives or as Astro JSX components (`<f.text k="key" />`) emitting DOM marker attributes (`data-cms-field`, `data-cms-entry-field`).
+- **Entry Scoping**: `f.entryScope('blog', entry.slug)` creates bound helpers that emit `data-cms-entry-field` for visual click-to-edit inside collection templates.
+- **Group Multiplication**: `f.group` defines reusable multi-field shapes instantiated at different prefixes (`Hero('home.hero')`, `Hero('about.hero')`), passing bound helpers to prop-drilled components.
+- **Preview Bridge Injection**: In preview requests (`/_preview/*?preview_token=...`) and Astro dev mode, the bridge IIFE is injected before `</body>` to handle handshake, capabilities (`capabilities: ['comments']`), click capturing, comment mode click suppression, anchor chain derivation, live `anchor-rects` streaming, outlines, and DOM patching.
+- **Dev-Server Middleware API**: In dev mode (`command === 'dev'`), Vite middleware mounts `/_cms/dev/*` for status, bundle, and draft field writes without polluting production bundles.
+- **Single Bundle Fetch**: Published bundle is fetched once per build and hydrated across all static pages synchronously via store singleton and `.cms/bundle.json`.
+- **Zero-Config Integration**: `cmsAstro()` accepts no arguments, automatically falling back to environment variables `CMS_SITE_ID` and `CMS_CONTENT_URL` populated by `cms link` (preview secrets are never stored on site hosts; preview tokens are verified directly by content-worker).
+- **AsyncLocalStorage Draft Overlay**: `runWithDraftBundle` overlays draft field values and entries inside SSR preview requests without mutating the global store.
+
+## Integrations
+
+- Consumes `@407dev/blocks` ([packages/blocks](../blocks)) for deterministic schema hashing and schema parsing.
+- Consumes `@407dev/field-types` ([packages/field-types](../field-types)) for field registry, validation, and link whitelisting.
+- Consumes `@407dev/config` ([packages/config](../config)) for dev tokens and path normalization.
+- Optionally consumes `@407dev/cli` ([packages/cli](../cli)) in dev mode for real-time template AST extraction diagnostics.
+- Consumed by consumer Astro applications (e.g. `examples/demo-site` ([examples/demo-site](../../examples/demo-site))).
+
+## Constraints
+
+- Published to public npm with ESM output and `.d.ts` declaration maps via `tsup`.
+- Any export change or signature alteration requires a changeset (`pnpm changeset`).
+- Zero direct database queries — communicates exclusively via edge content and draft HTTP endpoints.
+- Separate preview build topology: preview deployment sets `CMS_PREVIEW_BUILD=1` -> `output: 'server'` + Cloudflare adapter, whereas production builds default to `output: 'static'`. A site may still carry the Cloudflare adapter in a static production build to run other on-demand routes (e.g. `@407dev/site-services`'s injected `/_api/[...path]`) via per-route `prerender: false` — the adapter alone does not make the whole site server-rendered.
+- Dev routes and toolbar code are strictly excluded from production build outputs (`astro build`).
+
+## Gotchas
+
+- `CMS_DEV_TOKEN` is never exposed to the client or injected into `vite.define`; it is used exclusively by dev-server middleware for write-plane authorization.
+- In Astro preview middleware, `context.rewrite(targetPath)` must be returned directly to render the rewritten route; discarding its return value results in rendering nonexistent `/_preview/*` routes.
+- When rendering group fields in prop-drilled components, use bound accessors (`content.heading`) and spread `{...content.attrs()}` — do not call `f.text('literal')` internally inside shared components.
+- Invalid or expired preview tokens return `404 Not Found` (never exposing error details or unauthenticated drafts).
+- Preview responses must always be served with `Cache-Control: no-store` and `X-Robots-Tag: noindex`.
+- When mutating the DOM during in-place toolbar saves, MutationObservers are paused to avoid triggering re-entrant rescan loops.
+- Preview bridge and dev status editor origins are configured via `CMS_EDITOR_ORIGINS` (comma-separated) or explicit `editorOrigins` integration options; defaults to allowing both `https://web.localhost` and `http://localhost:5173`.
+- The injected preview bridge automatically suppresses the Astro dev toolbar (`astro-dev-toolbar { display: none !important; }`) when loaded inside an `<iframe>` (editor preview).
+- Comment mode cursor and click interception takes precedence over visual edit mode and link navigation whenever `data-cms-comment-mode` is set on `document.documentElement`.

package/dist/chunk-2TKIQIOE.js

@@ -0,0 +1,118 @@
+// ../design-tokens/src/tokens.ts
+var darkTokens = {
+  // Surfaces
+  background: "#0a0a0a",
+  // neutral-950
+  card: "#171717",
+  // neutral-900
+  cardForeground: "#f5f5f5",
+  // neutral-100
+  popover: "#171717",
+  popoverForeground: "#f5f5f5",
+  muted: "#262626",
+  // neutral-800
+  mutedForeground: "#a3a3a3",
+  // neutral-400
+  mutedStrong: "#404040",
+  // neutral-700
+  sunken: "#0a0a0a",
+  // neutral-950
+  secondary: "#262626",
+  secondaryForeground: "#f5f5f5",
+  accent: "#262626",
+  accentForeground: "#f5f5f5",
+  // Text
+  foreground: "#f5f5f5",
+  // neutral-100
+  foregroundSecondary: "#d4d4d4",
+  // neutral-300
+  foregroundSubtle: "#737373",
+  // neutral-500
+  // Borders
+  border: "#262626",
+  // neutral-800
+  borderStrong: "#404040",
+  // neutral-700
+  input: "#404040",
+  // neutral-700
+  outlineHalo: "#262626",
+  ring: "#6366f1",
+  // indigo-500
+  // Brand: Primary
+  primary: "#6366f1",
+  // indigo-500
+  primaryForeground: "#ffffff",
+  primaryText: "#a5b4fc",
+  // indigo-300
+  primaryMuted: "#1e1b4b",
+  // indigo-950
+  primaryBorder: "#3730a3",
+  // indigo-800
+  // Status: Success
+  success: "#34d399",
+  // emerald-400
+  successForeground: "#022c22",
+  successText: "#6ee7b7",
+  // emerald-300
+  successMuted: "#022c22",
+  // emerald-950
+  successBorder: "#065f46",
+  // emerald-800
+  // Status: Warning
+  warning: "#fbbf24",
+  // amber-400
+  warningForeground: "#451a03",
+  warningText: "#fcd34d",
+  // amber-300
+  warningMuted: "#451a03",
+  // amber-950
+  warningBorder: "#92400e",
+  // amber-800
+  // Status: Destructive
+  destructive: "#ef4444",
+  // red-500
+  destructiveForeground: "#ffffff",
+  destructiveText: "#fca5a5",
+  // red-300
+  destructiveMuted: "#450a0a",
+  // red-950
+  destructiveBorder: "#991b1b",
+  // red-800
+  // Status: Info
+  info: "#60a5fa",
+  // blue-400
+  infoForeground: "#ffffff",
+  infoText: "#93c5fd",
+  // blue-300
+  infoMuted: "#172554",
+  // blue-950
+  infoBorder: "#1e40af",
+  // blue-800
+  // Sidebar
+  sidebar: "#171717",
+  sidebarForeground: "#f5f5f5",
+  sidebarPrimary: "#6366f1",
+  sidebarPrimaryForeground: "#ffffff",
+  sidebarAccent: "#262626",
+  sidebarAccentForeground: "#f5f5f5",
+  sidebarBorder: "#262626",
+  sidebarRing: "#6366f1",
+  // Charts
+  chart1: "#6366f1",
+  // Brand Indigo
+  chart2: "#34d399",
+  // Emerald
+  chart3: "#fbbf24",
+  // Amber
+  chart4: "#a78bfa",
+  // Violet
+  chart5: "#38bdf8"
+  // Sky
+};
+var chromeTokens = {
+  ...darkTokens
+};
+
+export { chromeTokens };
+//# sourceMappingURL=chunk-2TKIQIOE.js.map
+//# sourceMappingURL=chunk-2TKIQIOE.js.map

package/dist/chunk-2TKIQIOE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../design-tokens/src/tokens.ts"],"names":[],"mappings":";AA+IO,IAAM,UAAA,GAA+B;AAAA;AAAA,EAE1C,UAAA,EAAY,SAAA;AAAA;AAAA,EACZ,IAAA,EAAM,SAAA;AAAA;AAAA,EACN,cAAA,EAAgB,SAAA;AAAA;AAAA,EAChB,OAAA,EAAS,SAAA;AAAA,EACT,iBAAA,EAAmB,SAAA;AAAA,EACnB,KAAA,EAAO,SAAA;AAAA;AAAA,EACP,eAAA,EAAiB,SAAA;AAAA;AAAA,EACjB,WAAA,EAAa,SAAA;AAAA;AAAA,EACb,MAAA,EAAQ,SAAA;AAAA;AAAA,EACR,SAAA,EAAW,SAAA;AAAA,EACX,mBAAA,EAAqB,SAAA;AAAA,EACrB,MAAA,EAAQ,SAAA;AAAA,EACR,gBAAA,EAAkB,SAAA;AAAA;AAAA,EAGlB,UAAA,EAAY,SAAA;AAAA;AAAA,EACZ,mBAAA,EAAqB,SAAA;AAAA;AAAA,EACrB,gBAAA,EAAkB,SAAA;AAAA;AAAA;AAAA,EAGlB,MAAA,EAAQ,SAAA;AAAA;AAAA,EACR,YAAA,EAAc,SAAA;AAAA;AAAA,EACd,KAAA,EAAO,SAAA;AAAA;AAAA,EACP,WAAA,EAAa,SAAA;AAAA,EACb,IAAA,EAAM,SAAA;AAAA;AAAA;AAAA,EAGN,OAAA,EAAS,SAAA;AAAA;AAAA,EACT,iBAAA,EAAmB,SAAA;AAAA,EACnB,WAAA,EAAa,SAAA;AAAA;AAAA,EACb,YAAA,EAAc,SAAA;AAAA;AAAA,EACd,aAAA,EAAe,SAAA;AAAA;AAAA;AAAA,EAGf,OAAA,EAAS,SAAA;AAAA;AAAA,EACT,iBAAA,EAAmB,SAAA;AAAA,EACnB,WAAA,EAAa,SAAA;AAAA;AAAA,EACb,YAAA,EAAc,SAAA;AAAA;AAAA,EACd,aAAA,EAAe,SAAA;AAAA;AAAA;AAAA,EAGf,OAAA,EAAS,SAAA;AAAA;AAAA,EACT,iBAAA,EAAmB,SAAA;AAAA,EACnB,WAAA,EAAa,SAAA;AAAA;AAAA,EACb,YAAA,EAAc,SAAA;AAAA;AAAA,EACd,aAAA,EAAe,SAAA;AAAA;AAAA;AAAA,EAGf,WAAA,EAAa,SAAA;AAAA;AAAA,EACb,qBAAA,EAAuB,SAAA;AAAA,EACvB,eAAA,EAAiB,SAAA;AAAA;AAAA,EACjB,gBAAA,EAAkB,SAAA;AAAA;AAAA,EAClB,iBAAA,EAAmB,SAAA;AAAA;AAAA;AAAA,EAGnB,IAAA,EAAM,SAAA;AAAA;AAAA,EACN,cAAA,EAAgB,SAAA;AAAA,EAChB,QAAA,EAAU,SAAA;AAAA;AAAA,EACV,SAAA,EAAW,SAAA;AAAA;AAAA,EACX,UAAA,EAAY,SAAA;AAAA;AAAA;AAAA,EAGZ,OAAA,EAAS,SAAA;AAAA,EACT,iBAAA,EAAmB,SAAA;AAAA,EACnB,cAAA,EAAgB,SAAA;AAAA,EAChB,wBAAA,EAA0B,SAAA;AAAA,EAC1B,aAAA,EAAe,SAAA;AAAA,EACf,uBAAA,EAAyB,SAAA;AAAA,EACzB,aAAA,EAAe,SAAA;AAAA,EACf,WAAA,EAAa,SAAA;AAAA;AAAA,EAGb,MAAA,EAAQ,SAAA;AAAA;AAAA,EACR,MAAA,EAAQ,SAAA;AAAA;AAAA,EACR,MAAA,EAAQ,SAAA;AAAA;AAAA,EACR,MAAA,EAAQ,SAAA;AAAA;AAAA,EACR,MAAA,EAAQ;AAAA;AACV,CAAA;AAMO,IAAM,YAAA,GAAiC;AAAA,EAC5C,GAAG;AACL","file":"chunk-2TKIQIOE.js","sourcesContent":["export interface ThemeColorTokens {\n  background: string;\n  card: string;\n  cardForeground: string;\n  popover: string;\n  popoverForeground: string;\n  muted: string;\n  mutedForeground: string;\n  mutedStrong: string;\n  sunken: string;\n  secondary: string;\n  secondaryForeground: string;\n  accent: string;\n  accentForeground: string;\n  foreground: string;\n  foregroundSecondary: string;\n  foregroundSubtle: string;\n  border: string;\n  borderStrong: string;\n  input: string;\n  outlineHalo: string;\n  ring: string;\n  primary: string;\n  primaryForeground: string;\n  primaryText: string;\n  primaryMuted: string;\n  primaryBorder: string;\n  success: string;\n  successForeground: string;\n  successText: string;\n  successMuted: string;\n  successBorder: string;\n  warning: string;\n  warningForeground: string;\n  warningText: string;\n  warningMuted: string;\n  warningBorder: string;\n  destructive: string;\n  destructiveForeground: string;\n  destructiveText: string;\n  destructiveMuted: string;\n  destructiveBorder: string;\n  info: string;\n  infoForeground: string;\n  infoText: string;\n  infoMuted: string;\n  infoBorder: string;\n  sidebar: string;\n  sidebarForeground: string;\n  sidebarPrimary: string;\n  sidebarPrimaryForeground: string;\n  sidebarAccent: string;\n  sidebarAccentForeground: string;\n  sidebarBorder: string;\n  sidebarRing: string;\n  chart1: string;\n  chart2: string;\n  chart3: string;\n  chart4: string;\n  chart5: string;\n}\n\nexport const lightTokens: ThemeColorTokens = {\n  // Surfaces\n  background: '#f6f6f6',\n  card: '#ffffff',\n  cardForeground: '#171717',\n  popover: '#ffffff',\n  popoverForeground: '#171717',\n  muted: '#f0f0f0',\n  mutedForeground: '#6b6b6b',\n  mutedStrong: '#e4e4e4',\n  sunken: '#f0f0f0',\n  secondary: '#f0f0f0',\n  secondaryForeground: '#171717',\n  accent: '#f0f0f0',\n  accentForeground: '#171717',\n\n  // Text\n  foreground: '#171717',\n  foregroundSecondary: '#4a4a4a',\n  foregroundSubtle: '#8a8a8a',\n\n  // Borders\n  border: '#e4e4e4',\n  borderStrong: '#bfbfbf',\n  input: '#bfbfbf',\n  outlineHalo: '#f0f0f0',\n  ring: '#0091ff',\n\n  // Brand: Primary\n  primary: '#0091ff',\n  primaryForeground: '#ffffff',\n  primaryText: '#006ec2',\n  primaryMuted: '#ebf6ff',\n  primaryBorder: '#b3e0ff',\n\n  // Status: Success\n  success: '#059669',\n  successForeground: '#ffffff',\n  successText: '#047857',\n  successMuted: '#ecfdf5',\n  successBorder: '#a7f3d0',\n\n  // Status: Warning\n  warning: '#d97706',\n  warningForeground: '#ffffff',\n  warningText: '#b45309',\n  warningMuted: '#fffbeb',\n  warningBorder: '#fde68a',\n\n  // Status: Destructive\n  destructive: '#dc2626',\n  destructiveForeground: '#ffffff',\n  destructiveText: '#b91c1c',\n  destructiveMuted: '#fef2f2',\n  destructiveBorder: '#fecaca',\n\n  // Status: Info\n  info: '#2563eb',\n  infoForeground: '#ffffff',\n  infoText: '#1d4ed8',\n  infoMuted: '#eff6ff',\n  infoBorder: '#bfdbfe',\n\n  // Sidebar\n  sidebar: '#ffffff',\n  sidebarForeground: '#171717',\n  sidebarPrimary: '#0091ff',\n  sidebarPrimaryForeground: '#ffffff',\n  sidebarAccent: '#f0f0f0',\n  sidebarAccentForeground: '#171717',\n  sidebarBorder: '#e4e4e4',\n  sidebarRing: '#0091ff',\n\n  // Charts\n  chart1: '#0091ff',\n  chart2: '#10b981',\n  chart3: '#f59e0b',\n  chart4: '#8b5cf6',\n  chart5: '#f43f5e',\n};\n\nexport const darkTokens: ThemeColorTokens = {\n  // Surfaces\n  background: '#0a0a0a', // neutral-950\n  card: '#171717', // neutral-900\n  cardForeground: '#f5f5f5', // neutral-100\n  popover: '#171717',\n  popoverForeground: '#f5f5f5',\n  muted: '#262626', // neutral-800\n  mutedForeground: '#a3a3a3', // neutral-400\n  mutedStrong: '#404040', // neutral-700\n  sunken: '#0a0a0a', // neutral-950\n  secondary: '#262626',\n  secondaryForeground: '#f5f5f5',\n  accent: '#262626',\n  accentForeground: '#f5f5f5',\n\n  // Text\n  foreground: '#f5f5f5', // neutral-100\n  foregroundSecondary: '#d4d4d4', // neutral-300\n  foregroundSubtle: '#737373', // neutral-500\n\n  // Borders\n  border: '#262626', // neutral-800\n  borderStrong: '#404040', // neutral-700\n  input: '#404040', // neutral-700\n  outlineHalo: '#262626',\n  ring: '#6366f1', // indigo-500\n\n  // Brand: Primary\n  primary: '#6366f1', // indigo-500\n  primaryForeground: '#ffffff',\n  primaryText: '#a5b4fc', // indigo-300\n  primaryMuted: '#1e1b4b', // indigo-950\n  primaryBorder: '#3730a3', // indigo-800\n\n  // Status: Success\n  success: '#34d399', // emerald-400\n  successForeground: '#022c22',\n  successText: '#6ee7b7', // emerald-300\n  successMuted: '#022c22', // emerald-950\n  successBorder: '#065f46', // emerald-800\n\n  // Status: Warning\n  warning: '#fbbf24', // amber-400\n  warningForeground: '#451a03',\n  warningText: '#fcd34d', // amber-300\n  warningMuted: '#451a03', // amber-950\n  warningBorder: '#92400e', // amber-800\n\n  // Status: Destructive\n  destructive: '#ef4444', // red-500\n  destructiveForeground: '#ffffff',\n  destructiveText: '#fca5a5', // red-300\n  destructiveMuted: '#450a0a', // red-950\n  destructiveBorder: '#991b1b', // red-800\n\n  // Status: Info\n  info: '#60a5fa', // blue-400\n  infoForeground: '#ffffff',\n  infoText: '#93c5fd', // blue-300\n  infoMuted: '#172554', // blue-950\n  infoBorder: '#1e40af', // blue-800\n\n  // Sidebar\n  sidebar: '#171717',\n  sidebarForeground: '#f5f5f5',\n  sidebarPrimary: '#6366f1',\n  sidebarPrimaryForeground: '#ffffff',\n  sidebarAccent: '#262626',\n  sidebarAccentForeground: '#f5f5f5',\n  sidebarBorder: '#262626',\n  sidebarRing: '#6366f1',\n\n  // Charts\n  chart1: '#6366f1', // Brand Indigo\n  chart2: '#34d399', // Emerald\n  chart3: '#fbbf24', // Amber\n  chart4: '#a78bfa', // Violet\n  chart5: '#38bdf8', // Sky\n};\n\n/**\n * Chrome tokens match dark tokens for tool surfaces (site editor shell & preview canvas)\n * so that editor chrome stays dark regardless of active page theme.\n */\nexport const chromeTokens: ThemeColorTokens = {\n  ...darkTokens,\n};\n\nexport const tokens = {\n  light: lightTokens,\n  dark: darkTokens,\n  chrome: chromeTokens,\n} as const;\n\nexport const typography = {\n  text3xs: { fontSize: '0.625rem', lineHeight: '0.875rem' }, // 10px / 14px\n  text2xs: { fontSize: '0.6875rem', lineHeight: '1rem' }, // 11px / 16px\n  textXs: { fontSize: '0.75rem', lineHeight: '1rem' }, // 12px / 16px\n  textSm: { fontSize: '0.875rem', lineHeight: '1.25rem' }, // 14px / 20px\n} as const;\n\nexport const radii = {\n  radius: '0.625rem',\n  sm: 'calc(0.625rem * 0.6)',\n  md: 'calc(0.625rem * 0.8)',\n  lg: '0.625rem',\n  xl: 'calc(0.625rem * 1.4)',\n  '2xl': 'calc(0.625rem * 1.8)',\n  '3xl': 'calc(0.625rem * 2.2)',\n  '4xl': 'calc(0.625rem * 2.6)',\n} as const;\n"]}