@saastro/studio 0.3.4 → 0.5.0

package/dist/index.js

@@ -1,8 +1,11 @@
 import {
   saastro
-} from "./chunk-SPY66EPD.js";
-import "./chunk-WBTB3A3Y.js";
-import "./chunk-RKHQDJVM.js";
+} from "./chunk-HEBSQKPT.js";
+import "./chunk-WTHLK3XQ.js";
+import "./chunk-MMUEPPBK.js";
+import {
+  editableImage
+} from "./chunk-FLFH5RVH.js";
 
 // src/helpers/editable-section.ts
 function editableSection(fieldPrefix) {
@@ -10,12 +13,6 @@ function editableSection(fieldPrefix) {
   return { "data-saastro": `sec:${fieldPrefix}` };
 }
 
-// src/helpers/editable-image.ts
-function editableImage(fieldPrefix) {
-  if (!fieldPrefix) return {};
-  return { "data-saastro": `img:${fieldPrefix}` };
-}
-
 // src/helpers/editable-slot.ts
 function editableSlot(fieldPrefix, slotName) {
   if (!fieldPrefix || !slotName) return {};

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/helpers/editable-section.ts","../src/helpers/editable-image.ts","../src/helpers/editable-slot.ts","../src/helpers/editable-array-item.ts","../src/index.ts"],"sourcesContent":["import type { EditableAttrs } from './types.js'\n\n/**\n * Section marker — drop on the root element of a component that\n * receives `fieldPrefix`. Lets the Studio overlay hover/select/drag\n * the whole section.\n *\n * Returns empty object when fieldPrefix is falsy — safe to spread unconditionally.\n */\nexport function editableSection(fieldPrefix: string | undefined): EditableAttrs {\n  if (!fieldPrefix) return {}\n  return { 'data-saastro': `sec:${fieldPrefix}` }\n}\n","import type { EditableAttrs } from './types.js'\n\n/**\n * Image marker — drop on `<img>` elements so Studio can offer an\n * image picker on click without leaving the preview.\n *\n * Returns empty object when fieldPrefix is falsy — safe to spread unconditionally.\n */\nexport function editableImage(fieldPrefix: string | undefined): EditableAttrs {\n  if (!fieldPrefix) return {}\n  return { 'data-saastro': `img:${fieldPrefix}` }\n}\n","import type { EditableAttrs } from './types.js'\n\n/**\n * Slot marker — used for discrete named edits within a section\n * (e.g. a CTA label inside a hero). `fieldPrefix` scopes the slot\n * to its parent component; `slotName` is the local identifier.\n *\n * Returns empty object when either argument is falsy — safe to spread unconditionally.\n */\nexport function editableSlot(\n  fieldPrefix: string | undefined,\n  slotName: string,\n): EditableAttrs {\n  if (!fieldPrefix || !slotName) return {}\n  return { 'data-saastro': `slot:${fieldPrefix}.${slotName}` }\n}\n","import type { EditableAttrs } from './types.js'\n\n/**\n * Array-item marker — used on each rendered item inside a `.map(...)`\n * over repeatable content (pricing plans, testimonials, feature cards).\n * Studio uses this to select/duplicate/reorder individual items.\n *\n * Format: `arr:{arrPath}[{index}]` — brackets follow JS/TS convention\n * (lodash, JSON Pointer) and avoid ambiguity with numeric literal keys.\n *\n * Returns empty object when fieldPrefix is falsy or index is negative/non-finite.\n */\nexport function editableArrayItem(\n  fieldPrefix: string | undefined,\n  index: number,\n): EditableAttrs {\n  if (!fieldPrefix || index < 0 || !Number.isFinite(index)) return {}\n  return { 'data-saastro': `arr:${fieldPrefix}[${index}]` }\n}\n","/**\n * @saastro/studio — build-time instrumentation for Saastro Studio.\n *\n * This package provides:\n * - **Astro Integration** (default export): `saastro({ autoWrap: true })` —\n *   registers the Vite plugin through Astro's own pipeline so ordering against\n *   the `.astro` compiler is deterministic on cold builds.\n * - **Editable helpers**: `editableSection`, `editableImage`, `editableSlot`,\n *   `editableArrayItem` + the `studioEditable` namespace.\n * - **Vite plugin** (separate entry, back-compat): `@saastro/studio/vite`.\n *\n * NOTE: This package is the *runtime instrumentation* installed in Astro\n * sites. The Studio editor UI lives at hub.saastro.io and is NOT part of this\n * package.\n *\n * @saastro/studio and @saastro/cms are peer packages — neither depends on the\n * other.\n */\n\nimport saastro from './integration/index.js'\n\nexport default saastro\nexport { saastro }\nexport type { SaastroStudioOptions } from './integration/index.js'\n\nexport type { EditableAttrs } from './helpers/types.js'\nexport { editableSection } from './helpers/editable-section.js'\nexport { editableImage } from './helpers/editable-image.js'\nexport { editableSlot } from './helpers/editable-slot.js'\nexport { editableArrayItem } from './helpers/editable-array-item.js'\n\nimport { editableSection } from './helpers/editable-section.js'\nimport { editableImage } from './helpers/editable-image.js'\nimport { editableSlot } from './helpers/editable-slot.js'\nimport { editableArrayItem } from './helpers/editable-array-item.js'\n\n/**\n * Convenience namespace — all four helpers grouped under one object.\n */\nexport const studioEditable = {\n  section: editableSection,\n  image: editableImage,\n  slot: editableSlot,\n  arrayItem: editableArrayItem,\n} as const\n"],"mappings":";;;;;;;AASO,SAAS,gBAAgB,aAAgD;AAC9E,MAAI,CAAC,YAAa,QAAO,CAAC;AAC1B,SAAO,EAAE,gBAAgB,OAAO,WAAW,GAAG;AAChD;;;ACJO,SAAS,cAAc,aAAgD;AAC5E,MAAI,CAAC,YAAa,QAAO,CAAC;AAC1B,SAAO,EAAE,gBAAgB,OAAO,WAAW,GAAG;AAChD;;;ACFO,SAAS,aACd,aACA,UACe;AACf,MAAI,CAAC,eAAe,CAAC,SAAU,QAAO,CAAC;AACvC,SAAO,EAAE,gBAAgB,QAAQ,WAAW,IAAI,QAAQ,GAAG;AAC7D;;;ACHO,SAAS,kBACd,aACA,OACe;AACf,MAAI,CAAC,eAAe,QAAQ,KAAK,CAAC,OAAO,SAAS,KAAK,EAAG,QAAO,CAAC;AAClE,SAAO,EAAE,gBAAgB,OAAO,WAAW,IAAI,KAAK,IAAI;AAC1D;;;ACGA,IAAO,cAAQ;AAkBR,IAAM,iBAAiB;AAAA,EAC5B,SAAS;AAAA,EACT,OAAO;AAAA,EACP,MAAM;AAAA,EACN,WAAW;AACb;","names":[]}
+{"version":3,"sources":["../src/helpers/editable-section.ts","../src/helpers/editable-slot.ts","../src/helpers/editable-array-item.ts","../src/index.ts"],"sourcesContent":["import type { EditableAttrs } from './types.js'\n\n/**\n * Section marker — drop on the root element of a component that\n * receives `fieldPrefix`. Lets the Studio overlay hover/select/drag\n * the whole section.\n *\n * Returns empty object when fieldPrefix is falsy — safe to spread unconditionally.\n */\nexport function editableSection(fieldPrefix: string | undefined): EditableAttrs {\n  if (!fieldPrefix) return {}\n  return { 'data-saastro': `sec:${fieldPrefix}` }\n}\n","import type { EditableAttrs } from './types.js'\n\n/**\n * Slot marker — used for discrete named edits within a section\n * (e.g. a CTA label inside a hero). `fieldPrefix` scopes the slot\n * to its parent component; `slotName` is the local identifier.\n *\n * Returns empty object when either argument is falsy — safe to spread unconditionally.\n */\nexport function editableSlot(\n  fieldPrefix: string | undefined,\n  slotName: string,\n): EditableAttrs {\n  if (!fieldPrefix || !slotName) return {}\n  return { 'data-saastro': `slot:${fieldPrefix}.${slotName}` }\n}\n","import type { EditableAttrs } from './types.js'\n\n/**\n * Array-item marker — used on each rendered item inside a `.map(...)`\n * over repeatable content (pricing plans, testimonials, feature cards).\n * Studio uses this to select/duplicate/reorder individual items.\n *\n * Format: `arr:{arrPath}[{index}]` — brackets follow JS/TS convention\n * (lodash, JSON Pointer) and avoid ambiguity with numeric literal keys.\n *\n * Returns empty object when fieldPrefix is falsy or index is negative/non-finite.\n */\nexport function editableArrayItem(\n  fieldPrefix: string | undefined,\n  index: number,\n): EditableAttrs {\n  if (!fieldPrefix || index < 0 || !Number.isFinite(index)) return {}\n  return { 'data-saastro': `arr:${fieldPrefix}[${index}]` }\n}\n","/**\n * @saastro/studio — build-time instrumentation for Saastro Studio.\n *\n * This package provides:\n * - **Astro Integration** (default export): `saastro({ autoWrap: true })` —\n *   registers the Vite plugin through Astro's own pipeline so ordering against\n *   the `.astro` compiler is deterministic on cold builds.\n * - **Editable helpers**: `editableSection`, `editableImage`, `editableSlot`,\n *   `editableArrayItem` + the `studioEditable` namespace.\n * - **Vite plugin** (separate entry, back-compat): `@saastro/studio/vite`.\n *\n * NOTE: This package is the *runtime instrumentation* installed in Astro\n * sites. The Studio editor UI lives at hub.saastro.io and is NOT part of this\n * package.\n *\n * @saastro/studio and @saastro/cms are peer packages — neither depends on the\n * other.\n */\n\nimport saastro from './integration/index.js'\n\nexport default saastro\nexport { saastro }\nexport type { SaastroStudioOptions } from './integration/index.js'\n\nexport type { EditableAttrs } from './helpers/types.js'\nexport { editableSection } from './helpers/editable-section.js'\nexport { editableImage } from './helpers/editable-image.js'\nexport { editableSlot } from './helpers/editable-slot.js'\nexport { editableArrayItem } from './helpers/editable-array-item.js'\n\nimport { editableSection } from './helpers/editable-section.js'\nimport { editableImage } from './helpers/editable-image.js'\nimport { editableSlot } from './helpers/editable-slot.js'\nimport { editableArrayItem } from './helpers/editable-array-item.js'\n\n/**\n * Convenience namespace — all four helpers grouped under one object.\n */\nexport const studioEditable = {\n  section: editableSection,\n  image: editableImage,\n  slot: editableSlot,\n  arrayItem: editableArrayItem,\n} as const\n"],"mappings":";;;;;;;;;;AASO,SAAS,gBAAgB,aAAgD;AAC9E,MAAI,CAAC,YAAa,QAAO,CAAC;AAC1B,SAAO,EAAE,gBAAgB,OAAO,WAAW,GAAG;AAChD;;;ACHO,SAAS,aACd,aACA,UACe;AACf,MAAI,CAAC,eAAe,CAAC,SAAU,QAAO,CAAC;AACvC,SAAO,EAAE,gBAAgB,QAAQ,WAAW,IAAI,QAAQ,GAAG;AAC7D;;;ACHO,SAAS,kBACd,aACA,OACe;AACf,MAAI,CAAC,eAAe,QAAQ,KAAK,CAAC,OAAO,SAAS,KAAK,EAAG,QAAO,CAAC;AAClE,SAAO,EAAE,gBAAgB,OAAO,WAAW,IAAI,KAAK,IAAI;AAC1D;;;ACGA,IAAO,cAAQ;AAkBR,IAAM,iBAAiB;AAAA,EAC5B,SAAS;AAAA,EACT,OAAO;AAAA,EACP,MAAM;AAAA,EACN,WAAW;AACb;","names":[]}

package/dist/integration/index.d.ts

@@ -1,5 +1,5 @@
 import { AstroIntegration } from 'astro';
-import { S as StudioAutoWrapOptions } from '../types-DlrT0PDc.js';
+import { S as StudioAutoWrapOptions } from '../types-C9q8CVtQ.js';
 
 type SaastroStudioOptions = StudioAutoWrapOptions;
 /**

package/dist/integration/index.js

@@ -1,8 +1,8 @@
 import {
   saastro
-} from "../chunk-SPY66EPD.js";
-import "../chunk-WBTB3A3Y.js";
-import "../chunk-RKHQDJVM.js";
+} from "../chunk-HEBSQKPT.js";
+import "../chunk-WTHLK3XQ.js";
+import "../chunk-MMUEPPBK.js";
 export {
   saastro as default
 };

package/dist/middleware/index.js

@@ -1,7 +1,7 @@
 import {
   injectVersionMetaTag,
   injectVisibilityStyle
-} from "../chunk-RKHQDJVM.js";
+} from "../chunk-MMUEPPBK.js";
 
 // src/middleware/index.ts
 var HTML_RE = /text\/html/i;

package/dist/types-C9q8CVtQ.d.ts

@@ -0,0 +1,38 @@
+interface StudioAutoWrapOptions {
+    /** Turn on the auto-wrap transform. Off by default. */
+    autoWrap?: boolean;
+    /**
+     * Also auto-instrument whole route files under `src/pages/**` that carry
+     * NEITHER a hand-written `data-saastro` marker NOR a `fieldPrefix` prop.
+     * For each such page we match the route (`show.astro`, `our-team.astro`,
+     * `index.astro` → `home`; `[locale]`/static-locale dirs transparent) to the
+     * page's OWN i18n namespace — the `t.<ns>` it actually reads — and stamp
+     * `data-saastro="sec:<ns>"` on the first content element. Using the real
+     * namespace means it works whatever the naming convention (`ourTeam` or
+     * `our_team`, `faq`…) and never invents a key the Studio can't resolve. The
+     * Studio then derives editable fields from that namespace — so a NEW page
+     * becomes editable with zero code in the customer repo.
+     *
+     * Opt-in, off by default. Requires `autoWrap: true` (it extends the
+     * section-level transform; it does nothing on its own). Conservative: marks
+     * only when a referenced namespace matches the route — otherwise it leaves
+     * the page for the Hub's Studio doctor to flag. Dynamic routes
+     * (`[slug].astro`) are skipped.
+     */
+    autoWrapPages?: boolean;
+    /**
+     * Only transform files whose path matches this predicate. Default:
+     * every `.astro`, `.tsx`, `.jsx` file (further filtered by per-file
+     * heuristics — fieldPrefix on Astro, Props + `.map(` on TSX).
+     */
+    include?: (id: string) => boolean;
+    /**
+     * Instrument React components (.tsx/.jsx) whose Props match field
+     * names. When enabled, `.map((item, i) => <jsx/>)` patterns get
+     * `data-saastro-field` markers on the iterated element and on
+     * `{item.<sub>}` references. Defaults to `true`.
+     */
+    instrumentTsx?: boolean;
+}
+
+export type { StudioAutoWrapOptions as S };

package/dist/vite/index.d.ts

@@ -1,5 +1,5 @@
 import { Plugin } from 'vite';
-import { S as StudioAutoWrapOptions } from '../types-DlrT0PDc.js';
+import { S as StudioAutoWrapOptions } from '../types-C9q8CVtQ.js';
 
 /**
  * Vite plugin factory for Saastro Studio instrumentation.

package/dist/vite/index.js

@@ -1,7 +1,7 @@
 import {
   studioAutoWrap
-} from "../chunk-WBTB3A3Y.js";
-import "../chunk-RKHQDJVM.js";
+} from "../chunk-WTHLK3XQ.js";
+import "../chunk-MMUEPPBK.js";
 export {
   studioAutoWrap as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saastro/studio",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "description": "Build-time instrumentation for Saastro Studio — Vite plugin + editable helpers for Astro sites managed by Saastro Hub",
   "license": "MIT",
   "author": "SAASTRO",
@@ -37,10 +37,16 @@
     "./middleware": {
       "types": "./dist/middleware/index.d.ts",
       "import": "./dist/middleware/index.js"
-    }
+    },
+    "./image": {
+      "types": "./dist/image/index.d.ts",
+      "import": "./dist/image/index.js"
+    },
+    "./Img.astro": "./src/Img.astro"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/Img.astro"
   ],
   "peerDependencies": {
     "astro": "^5.0.0 || ^6.0.0",

package/src/Img.astro

@@ -0,0 +1,124 @@
+---
+/**
+ * <Img> — edge-optimized, Studio-editable image for Saastro CMS sites.
+ *
+ * - Optimizes via Cloudflare Image Transformations (`/cdn-cgi/image/...`) at the
+ *   zone edge — webp/avif + responsive srcset, no Sharp (works on SSR/Workers).
+ * - Handles BOTH a repo asset (`/images/...`, transformed root-relative on the
+ *   site's own zone) AND an R2 media-library upload (`https://media.saastro.io/...`,
+ *   transformed on the media host).
+ * - Stays EDITABLE: when `fieldPrefix` is set, the `<img>` carries the RAW src +
+ *   the Studio marker (`editableImage`), while the optimized candidates live on
+ *   `<source srcset>`. The overlay reads/writes the raw `<img src>` → round-trips
+ *   cleanly into content (it must never see a `/cdn-cgi/image/...` URL).
+ * - Degrades gracefully: in `astro dev`, on localhost, with `raw`, or for
+ *   svg/gif/remote sources, emits a plain `<img>` (identical to today).
+ *
+ * Ships with @saastro/studio (consumed via the `./Img.astro` export). The marker
+ * helper `editableImage` is native to this package; the raw-src requirement is
+ * dictated by the Hub overlay (apps/hub-react/src/server/studio/overlay-script.ts).
+ */
+import { buildImage, editableImage, DEFAULT_WIDTHS } from '@saastro/studio/image'
+
+interface Props {
+  /** `/images/...` (repo) or `https://media.saastro.io/...` (R2). */
+  src: string
+  alt: string
+  width?: number
+  height?: number
+  /** Responsive `sizes`; default `100vw`. */
+  sizes?: string
+  /** srcset breakpoints (px); default [480,768,1024,1536,2048]. */
+  widths?: number[]
+  quality?: number
+  fit?: 'cover' | 'contain' | 'scale-down'
+  loading?: 'lazy' | 'eager'
+  fetchpriority?: 'high' | 'low' | 'auto'
+  decoding?: 'async' | 'sync' | 'auto'
+  /** Studio editability: emits `data-saastro="img:<fieldPrefix>"`. */
+  fieldPrefix?: string
+  class?: string
+  /** Force-disable CF transforms for this instance (serve the raw src). */
+  raw?: boolean
+  /** Override the media host (default `media.saastro.io`). */
+  mediaHost?: string
+  [key: string]: unknown
+}
+
+const {
+  src,
+  alt,
+  width,
+  height,
+  sizes = '100vw',
+  widths,
+  quality = 80,
+  fit,
+  loading = 'lazy',
+  fetchpriority,
+  decoding = 'async',
+  fieldPrefix,
+  class: className,
+  raw = false,
+  mediaHost,
+  ...rest
+} = Astro.props
+
+// Only emit /cdn-cgi/image URLs where a CF edge will actually serve them.
+// `import.meta.env.DEV` is statically true in `astro dev` (no edge there);
+// the host check is a belt-and-suspenders guard for `astro preview` /
+// `wrangler dev`; PUBLIC_SAASTRO_IMG_RAW is a per-environment kill switch.
+const isDev = import.meta.env.DEV === true
+const reqHost = Astro.request.headers.get('host') ?? ''
+const isLocalHost = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(reqHost)
+const forceRaw = import.meta.env.PUBLIC_SAASTRO_IMG_RAW === '1'
+const optimize = !isDev && !isLocalHost && !forceRaw && !raw
+
+const img = buildImage({
+  src,
+  widths: widths ?? [...DEFAULT_WIDTHS],
+  quality,
+  fit,
+  optimize,
+  mediaHost,
+})
+
+const editAttrs = editableImage(fieldPrefix)
+const isEditable = !!fieldPrefix
+---
+
+{
+  img.srcset ? (
+    <picture>
+      {/* One <source>: `format=auto` already negotiates avif/webp/jpeg at the
+          edge, so a single transformed srcset is enough. */}
+      <source srcset={img.srcset} sizes={sizes} />
+      <img
+        src={isEditable ? img.rawSrc : (img.optimizedSrc ?? img.rawSrc)}
+        alt={alt}
+        width={width}
+        height={height}
+        sizes={sizes}
+        loading={loading}
+        fetchpriority={fetchpriority}
+        decoding={decoding}
+        class={className}
+        {...editAttrs}
+        {...rest}
+      />
+    </picture>
+  ) : (
+    <img
+      src={img.rawSrc}
+      alt={alt}
+      width={width}
+      height={height}
+      loading={loading}
+      fetchpriority={fetchpriority}
+      decoding={decoding}
+      class={className}
+      {...editAttrs}
+      {...rest}
+    />
+  )
+}