camox 0.41.1 → 0.43.0

package/dist/core/createApp.js

@@ -7,7 +7,7 @@ function createApp({ blocks, layouts = [] }) {
 	for (const layout of layouts) {
 		const { id, kind } = layout._internal;
 		if (layoutsMap.has(id)) throw new Error(`Duplicate layout: ${id}`);
-		if (kind === "derived") {
+		if (kind !== "curated") {
 			const pattern = id.split(".").map((segment) => segment.startsWith("$") ? "$" : segment).join(".");
 			if (derivedPatterns.has(pattern)) throw new Error(`Equivalent derived route: ${id}`);
 			derivedPatterns.add(pattern);
@@ -46,6 +46,7 @@ function createApp({ blocks, layouts = [] }) {
 		getSerializableLayoutDefinitions() {
 			return Array.from(layoutsMap.values()).map((layout) => ({
 				layoutId: layout._internal.id,
+				kind: layout._internal.kind,
 				description: layout._internal.description,
 				blocks: layout._internal.blockDefinitions
 			}));

package/dist/core/createLayout.d.ts

@@ -51,7 +51,7 @@ type ValidateLayoutOnlyBlocks<T extends readonly LayoutBlock[]> = { [K in keyof
 type ValidatePageContentBlocks<T extends readonly LayoutBlock[]> = { [K in keyof T]: T[K] extends LayoutBlock<true> ? "❌ Camox: blocks in `blocks.initial` must NOT be `layoutOnly: true` — `initial` is for page-content blocks. Remove `layoutOnly: true` from this block's `createBlock` options." : T[K] };
 interface CreateLayoutOptions<TBefore extends readonly LayoutBlock[], TAfter extends readonly LayoutBlock[], TInitial extends readonly LayoutBlock[]> {
   id: string;
-  kind?: "curated" | "derived";
+  kind?: "curated" | "derived" | "singleton";
   loader?: (context: {
     params: Record<string, string>;
   }) => unknown;
@@ -84,7 +84,7 @@ declare function createLayoutDefinition<const TBefore extends readonly LayoutBlo
   useData(): unknown;
   _internal: {
     id: string;
-    kind: "curated" | "derived";
+    kind: "curated" | "derived" | "singleton";
     loader: ((context: {
       params: Record<string, string>;
     }) => unknown) | undefined;
@@ -156,6 +156,19 @@ type FileOptions<Id extends string, Data, B extends readonly LayoutBlock[], A ex
     children: React.ReactNode;
   }>;
   loader?: never;
+} | {
+  kind: "singleton";
+  blocks: {
+    before: ValidateLayoutOnlyBlocks<B>;
+    after: ValidateLayoutOnlyBlocks<A>;
+    initial?: never;
+  };
+  loader?: (context: {
+    params: Record<string, never>;
+  }) => Data;
+  component: React.ComponentType<{
+    children?: never;
+  }>;
 } | {
   kind: "derived";
   blocks: {
@@ -172,7 +185,7 @@ type FileOptions<Id extends string, Data, B extends readonly LayoutBlock[], A ex
     children?: never;
   }>;
 });
-declare function createLayout<const Id extends string>(id: Id): <Data, const B extends readonly LayoutBlock[], const A extends readonly LayoutBlock[], const I extends readonly LayoutBlock[] = []>(options: FileOptions<Id, Data, B, A, I>) => Omit<Layout, "useData"> & {
+declare function createLayout<const Id extends string>(id: Id): <Data = undefined, const B extends readonly LayoutBlock[] = [], const A extends readonly LayoutBlock[] = [], const I extends readonly LayoutBlock[] = []>(options: FileOptions<Id, Data, B, A, I>) => Omit<Layout, "useData"> & {
   useData: () => Awaited<Data>;
 };
 declare function createLayout<const B extends readonly LayoutBlock[], const A extends readonly LayoutBlock[], const I extends readonly LayoutBlock[] = []>(options: CreateLayoutOptions<B, A, I>): Layout;

package/dist/core/createLayout.js

@@ -5,15 +5,17 @@ import { Fragment, jsx } from "react/jsx-runtime";
 
 //#region src/core/createLayout.tsx
 function createLayoutDefinition(options) {
+	if (options.kind === "singleton" && !/^[\w-]+(?:\.[\w-]+)*$/.test(options.id)) throw new Error(`Singleton layouts require a fixed file route: ${options.id}`);
+	if (options.kind && options.kind !== "curated" && options.blocks.initial) throw new Error("Code-owned layouts cannot define initial page blocks");
 	const LayoutContext = React.createContext(null);
 	const beforeBlocks = options.blocks.before;
 	const afterBlocks = options.blocks.after;
 	const initialBlocks = options.blocks.initial;
 	const BeforeBlocks = () => {
 		const $ = c(5);
-		if ($[0] !== "2ae925f72331cad3d35d77334ec5712b5849211fd0dcab4e27af95282e583b7a") {
+		if ($[0] !== "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433") {
 			for (let $i = 0; $i < 5; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-			$[0] = "2ae925f72331cad3d35d77334ec5712b5849211fd0dcab4e27af95282e583b7a";
+			$[0] = "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433";
 		}
 		const ctx = React.use(LayoutContext);
 		if (!ctx) throw new Error(`Layout "${options.id}" BeforeBlocks must be rendered inside its Provider`);
@@ -29,7 +31,7 @@ function createLayoutDefinition(options) {
 					children: /* @__PURE__ */ jsx(block._internal.Component, {
 						blockData,
 						mode: "layout",
-						showAddBlockBottom: options.kind !== "derived" && isLastBefore || void 0,
+						showAddBlockBottom: (options.kind ?? "curated") === "curated" && isLastBefore || void 0,
 						addBlockAfterPosition: isLastBefore ? "" : void 0
 					})
 				}, block._internal.id);
@@ -48,9 +50,9 @@ function createLayoutDefinition(options) {
 	BeforeBlocks.displayName = `LayoutBeforeBlocks(${options.id})`;
 	const AfterBlocks = () => {
 		const $ = c(5);
-		if ($[0] !== "2ae925f72331cad3d35d77334ec5712b5849211fd0dcab4e27af95282e583b7a") {
+		if ($[0] !== "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433") {
 			for (let $i = 0; $i < 5; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-			$[0] = "2ae925f72331cad3d35d77334ec5712b5849211fd0dcab4e27af95282e583b7a";
+			$[0] = "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433";
 		}
 		const ctx = React.use(LayoutContext);
 		if (!ctx) throw new Error(`Layout "${options.id}" AfterBlocks must be rendered inside its Provider`);
@@ -66,7 +68,7 @@ function createLayoutDefinition(options) {
 					children: /* @__PURE__ */ jsx(block._internal.Component, {
 						blockData,
 						mode: "layout",
-						showAddBlockTop: options.kind !== "derived" && isFirstAfter || void 0,
+						showAddBlockTop: (options.kind ?? "curated") === "curated" && isFirstAfter || void 0,
 						addBlockAfterPosition: isFirstAfter ? null : void 0
 					})
 				}, block._internal.id);
@@ -85,9 +87,9 @@ function createLayoutDefinition(options) {
 	AfterBlocks.displayName = `LayoutAfterBlocks(${options.id})`;
 	const Provider = (t0) => {
 		const $ = c(7);
-		if ($[0] !== "2ae925f72331cad3d35d77334ec5712b5849211fd0dcab4e27af95282e583b7a") {
+		if ($[0] !== "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433") {
 			for (let $i = 0; $i < 7; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-			$[0] = "2ae925f72331cad3d35d77334ec5712b5849211fd0dcab4e27af95282e583b7a";
+			$[0] = "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433";
 		}
 		const { layoutBlocks, children, data } = t0;
 		let t1;
@@ -133,6 +135,7 @@ function createLayoutDefinition(options) {
 		};
 	})];
 	const buildOgImage = options.buildOgImage ? async (params) => {
+		if (import.meta.env?.SSR === false) throw new Error("OG images can only be rendered on the server.");
 		const { ImageResponse } = await import("camox/_internal/imageResponse");
 		return new ImageResponse(options.buildOgImage(params), {
 			width: 1200,
@@ -173,13 +176,10 @@ function createLayoutDefinition(options) {
 }
 function createLayout(idOrOptions) {
 	if (typeof idOrOptions !== "string") return createLayoutDefinition(idOrOptions);
-	return (options) => {
-		if (options.kind === "derived" && options.blocks.initial) throw new Error("Derived layouts cannot define initial page blocks");
-		return createLayoutDefinition({
-			...options,
-			id: idOrOptions
-		});
-	};
+	return (options) => createLayoutDefinition({
+		...options,
+		id: idOrOptions
+	});
 }
 /** Signal a missing derived page; other loader failures remain server errors. */
 function notFound() {

package/dist/core/derivedRoutes.js

@@ -4,7 +4,7 @@ function routeSegments(id) {
 }
 function matchDerivedLayout(layouts, pathname) {
 	const path = pathname.replace(/^\/|\/$/g, "").split("/");
-	const candidates = layouts.filter((layout) => layout._internal.kind === "derived").sort((a, b) => routeSegments(a._internal.id).filter((s) => s.startsWith("$")).length - routeSegments(b._internal.id).filter((s) => s.startsWith("$")).length);
+	const candidates = layouts.filter((layout) => layout._internal.kind !== "curated").sort((a, b) => routeSegments(a._internal.id).filter((s) => s.startsWith("$")).length - routeSegments(b._internal.id).filter((s) => s.startsWith("$")).length);
 	for (const layout of candidates) {
 		const segments = routeSegments(layout._internal.id);
 		if (segments.length !== path.length) continue;

package/dist/core/dom.d.ts

@@ -0,0 +1,17 @@
+//#region src/core/dom.d.ts
+/** The browsing context that owns a rendered element. */
+interface ElementContext {
+  document: Document;
+  window: Window & typeof globalThis;
+}
+/**
+ * Resolve DOM APIs from an element rather than the component's JavaScript realm.
+ * In Camox preview, elements belong to an iframe but component globals belong
+ * to the editor. Call this after mounting (for example, inside an effect).
+ *
+ * Returns null for a missing element or a document without a window. Never
+ * falls back to globals. This does not convert objects into the target realm.
+ */
+declare function getElementContext(element: Element | null | undefined): ElementContext | null;
+//#endregion
+export { ElementContext, getElementContext };

package/dist/core/dom.js

@@ -0,0 +1,22 @@
+//#region src/core/dom.ts
+/**
+* Resolve DOM APIs from an element rather than the component's JavaScript realm.
+* In Camox preview, elements belong to an iframe but component globals belong
+* to the editor. Call this after mounting (for example, inside an effect).
+*
+* Returns null for a missing element or a document without a window. Never
+* falls back to globals. This does not convert objects into the target realm.
+*/
+function getElementContext(element) {
+	if (!element) return null;
+	const document = element.ownerDocument;
+	const window = document.defaultView;
+	if (!window) return null;
+	return {
+		document,
+		window
+	};
+}
+
+//#endregion
+export { getElementContext };

package/dist/core/editing/createEditableBlock.d.ts

@@ -115,9 +115,10 @@ declare function createEditableBlock<TSchemaShape extends Record<string, TSchema
     children
   }: {
     children: (props: {
+      "data-camox-comment-block-id"?: number;
       ref: (element: HTMLElement | null) => void;
       style: React.CSSProperties;
-      onClick: (e: React.MouseEvent) => void;
+      onClickCapture: (e: React.MouseEvent) => void;
       onMouseEnter: () => void;
       onMouseLeave: () => void;
     }) => React.ReactNode;
@@ -171,6 +172,7 @@ declare function createEditableBlock<TSchemaShape extends Record<string, TSchema
       "data-camox-overlay-mode"?: string;
       onMouseEnter?: () => void;
       onMouseLeave?: () => void;
+      onClickCapture?: (event: React.MouseEvent<HTMLElement>) => void;
     }, data: {
       /** Raw markdown source. Use `props.children` for rendered content. */text: string;
     }) => React.ReactNode;
@@ -260,6 +262,7 @@ declare function createEditableBlock<TSchemaShape extends Record<string, TSchema
       "data-camox-overlay-mode"?: string;
       onMouseEnter?: () => void;
       onMouseLeave?: () => void;
+      onClickCapture?: (event: React.MouseEvent<HTMLElement>) => void;
     }, data: {
       text: string;
       href: string;
@@ -530,6 +533,7 @@ declare function createEditableBlock<TSchemaShape extends Record<string, TSchema
           "data-camox-overlay-mode"?: string;
           onMouseEnter?: () => void;
           onMouseLeave?: () => void;
+          onClickCapture?: (event: React.MouseEvent<HTMLElement>) => void;
         }, data: {
           /** Raw markdown source. Use `props.children` for rendered content. */text: string;
         }) => React.ReactNode;
@@ -629,6 +633,7 @@ declare function createEditableBlock<TSchemaShape extends Record<string, TSchema
           "data-camox-overlay-mode"?: string;
           onMouseEnter?: () => void;
           onMouseLeave?: () => void;
+          onClickCapture?: (event: React.MouseEvent<HTMLElement>) => void;
         }, data: {
           text: string;
           href: string;
@@ -1254,6 +1259,7 @@ declare function createEditableBlock<TSchemaShape extends Record<string, TSchema
               "data-camox-overlay-mode"?: string;
               onMouseEnter?: () => void;
               onMouseLeave?: () => void;
+              onClickCapture?: (event: React.MouseEvent<HTMLElement>) => void;
             }, data: {
               /** Raw markdown source. Use `props.children` for rendered content. */text: string;
             }) => React.ReactNode;
@@ -1281,6 +1287,7 @@ declare function createEditableBlock<TSchemaShape extends Record<string, TSchema
               "data-camox-overlay-mode"?: string;
               onMouseEnter?: () => void;
               onMouseLeave?: () => void;
+              onClickCapture?: (event: React.MouseEvent<HTMLElement>) => void;
             }, data: {
               text: string;
               href: string;