@fullgrainsoftware/portal 0.9.0

package/dist/manifest.d.ts

@@ -0,0 +1,297 @@
+import { z } from "zod";
+export type FieldType = "text" | "image" | "color" | "audio" | "video";
+export interface ManifestField {
+    label: string;
+    type: FieldType;
+    required?: boolean;
+    default?: string;
+    allowTypeChange?: boolean;
+    allowedTypes?: readonly FieldType[];
+    generateMp4?: boolean;
+}
+export interface ManifestSeedItem {
+    name: string;
+    values: Record<string, string>;
+}
+export interface ManifestSection {
+    key: string;
+    title: string;
+    kind: "repeatable" | "singleton";
+    allowGroupCreation?: boolean;
+    fields: Record<string, ManifestField>;
+    seed?: readonly ManifestSeedItem[];
+}
+export interface ManifestPage {
+    slug: string;
+    title: string;
+    sections: readonly ManifestSection[];
+}
+export interface SiteManifest {
+    alias: string;
+    pages: readonly ManifestPage[];
+}
+export declare function defineSite<const T extends SiteManifest>(manifest: T): T;
+export declare const siteManifestSchema: z.ZodEffects<z.ZodObject<{
+    alias: z.ZodString;
+    pages: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        title: z.ZodString;
+        sections: z.ZodArray<z.ZodEffects<z.ZodObject<{
+            key: z.ZodString;
+            title: z.ZodString;
+            kind: z.ZodEnum<["repeatable", "singleton"]>;
+            allowGroupCreation: z.ZodOptional<z.ZodBoolean>;
+            fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+                label: z.ZodString;
+                type: z.ZodEnum<["text", "image", "color", "audio", "video"]>;
+                required: z.ZodOptional<z.ZodBoolean>;
+                default: z.ZodOptional<z.ZodString>;
+                allowTypeChange: z.ZodOptional<z.ZodBoolean>;
+                allowedTypes: z.ZodOptional<z.ZodArray<z.ZodEnum<["text", "image", "color", "audio", "video"]>, "many">>;
+                generateMp4: z.ZodOptional<z.ZodBoolean>;
+            }, "strict", z.ZodTypeAny, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>>;
+            seed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                values: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                values: Record<string, string>;
+                name: string;
+            }, {
+                values: Record<string, string>;
+                name: string;
+            }>, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }, {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }>, {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }, {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        slug: string;
+        sections: {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }[];
+    }, {
+        title: string;
+        slug: string;
+        sections: {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }[];
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    alias: string;
+    pages: {
+        title: string;
+        slug: string;
+        sections: {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }[];
+    }[];
+}, {
+    alias: string;
+    pages: {
+        title: string;
+        slug: string;
+        sections: {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }[];
+    }[];
+}>, {
+    alias: string;
+    pages: {
+        title: string;
+        slug: string;
+        sections: {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }[];
+    }[];
+}, {
+    alias: string;
+    pages: {
+        title: string;
+        slug: string;
+        sections: {
+            key: string;
+            title: string;
+            kind: "repeatable" | "singleton";
+            fields: Record<string, {
+                label: string;
+                type: "text" | "image" | "color" | "audio" | "video";
+                default?: string | undefined;
+                required?: boolean | undefined;
+                allowTypeChange?: boolean | undefined;
+                allowedTypes?: ("text" | "image" | "color" | "audio" | "video")[] | undefined;
+                generateMp4?: boolean | undefined;
+            }>;
+            allowGroupCreation?: boolean | undefined;
+            seed?: {
+                values: Record<string, string>;
+                name: string;
+            }[] | undefined;
+        }[];
+    }[];
+}>;

package/dist/manifest.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+// Identity function whose const type parameter preserves literal keys/kinds,
+// which is what makes readSiteContent's return type precise.
+export function defineSite(manifest) {
+    return manifest;
+}
+// ---- Runtime validation (canonical copy; ab-cms/src/lib/site-manifest.ts mirrors it) ----
+const fieldTypeSchema = z.enum(["text", "image", "color", "audio", "video"]);
+const fieldSchema = z
+    .object({
+    label: z.string().trim().min(1),
+    type: fieldTypeSchema,
+    required: z.boolean().optional(),
+    default: z.string().optional(),
+    allowTypeChange: z.boolean().optional(),
+    allowedTypes: z.array(fieldTypeSchema).optional(),
+    generateMp4: z.boolean().optional(),
+})
+    .strict();
+const seedItemSchema = z
+    .object({
+    name: z.string().trim().min(1),
+    values: z.record(z.string(), z.string()),
+})
+    .strict();
+const sectionSchema = z
+    .object({
+    key: z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, "section key must be a valid identifier"),
+    title: z.string().trim().min(1),
+    kind: z.enum(["repeatable", "singleton"]),
+    allowGroupCreation: z.boolean().optional(),
+    fields: z.record(z.string().regex(/^[a-z][a-z0-9-]*$/, "field keys are lower-kebab"), fieldSchema),
+    seed: z.array(seedItemSchema).optional(),
+})
+    .strict()
+    .superRefine((section, ctx) => {
+    if (Object.keys(section.fields).length === 0) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "section needs at least one field" });
+    }
+    if (section.kind === "singleton" && (section.seed?.length ?? 0) > 1) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "singleton sections take at most one seed item" });
+    }
+    // A component's CMS identity is its (normalized) label, so two fields whose
+    // labels collide would collapse onto one component — last write wins,
+    // reattaching content to the wrong field. Enforce label uniqueness.
+    const seenLabels = new Set();
+    for (const field of Object.values(section.fields)) {
+        const norm = field.label.trim().toLowerCase();
+        if (seenLabels.has(norm)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `duplicate field label "${field.label}" — field labels must be unique within a section`,
+            });
+        }
+        seenLabels.add(norm);
+    }
+    for (const item of section.seed ?? []) {
+        for (const valueKey of Object.keys(item.values)) {
+            if (!Object.hasOwn(section.fields, valueKey)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `seed "${item.name}" sets unknown field "${valueKey}"`,
+                });
+            }
+        }
+    }
+});
+const pageSchema = z
+    .object({
+    slug: z.string().trim().min(1),
+    title: z.string().trim().min(1),
+    sections: z.array(sectionSchema),
+})
+    .strict();
+export const siteManifestSchema = z
+    .object({
+    alias: z.string().trim().min(1),
+    pages: z.array(pageSchema).min(1),
+})
+    .strict()
+    .superRefine((manifest, ctx) => {
+    const slugs = new Set();
+    const sectionKeys = new Set();
+    for (const page of manifest.pages) {
+        if (slugs.has(page.slug)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate page slug "${page.slug}"` });
+        }
+        slugs.add(page.slug);
+        const titles = new Set();
+        for (const section of page.sections) {
+            if (sectionKeys.has(section.key)) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate section key "${section.key}"` });
+            }
+            sectionKeys.add(section.key);
+            const t = section.title.toLowerCase();
+            if (titles.has(t)) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate section title "${section.title}" on ${page.slug}` });
+            }
+            titles.add(t);
+        }
+    }
+});

package/dist/preview.d.ts

@@ -0,0 +1,49 @@
+export declare const PREVIEW_PROTOCOL_VERSION = 1;
+export declare const PREVIEW_QUERY_FLAG = "cms-preview";
+/** Message the embedded site sends up to the dashboard. */
+export type PreviewOutbound = {
+    source: "ab-cms-preview";
+    v: number;
+    type: "ready";
+    sections: string[];
+} | {
+    source: "ab-cms-preview";
+    v: number;
+    type: "section-clicked";
+    title: string;
+} | {
+    source: "ab-cms-preview";
+    v: number;
+    type: "edit-item";
+    id: string;
+};
+/** Message the dashboard sends down to the embedded site. */
+export type PreviewInbound = {
+    source: "ab-cms-dashboard";
+    v: number;
+    type: "scroll-to-section";
+    title: string;
+} | {
+    source: "ab-cms-dashboard";
+    v: number;
+    type: "refresh";
+};
+/** Type guard + version check for messages arriving from the dashboard. */
+export declare function parseInbound(data: unknown): PreviewInbound | null;
+export declare function readyMessage(sections: string[]): PreviewOutbound;
+export declare function sectionClickedMessage(title: string): PreviewOutbound;
+export declare function editItemMessage(id: string): PreviewOutbound;
+export interface CmsPreviewOptions {
+    /**
+     * Origins allowed to embed and message this preview. Messages from any other
+     * origin are ignored, and outbound messages target only these. Defaults to
+     * the Fullgrain Portal dashboard origins only — for local development against a
+     * dev panel, pass your localhost origin (e.g. ["http://localhost:3000"]).
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * Activate the preview bridge. Safe to call unconditionally: it no-ops on the
+ * server and on the public (non-preview) site. Returns a cleanup function.
+ */
+export declare function initCmsPreview(options?: CmsPreviewOptions): () => void;

package/dist/preview.js

@@ -0,0 +1,165 @@
+// Live-preview bridge. A site includes this (via initCmsPreview) so the
+// Fullgrain Portal dashboard can embed it in an iframe and drive it: scroll to a section,
+// refresh after a save, and — when a visitor clicks a tagged section in the
+// preview — tell the dashboard to select it.
+//
+// The site tags each section's root element with data-cms-section="<title>",
+// matching the CMS section title. Nothing here runs on the public site: the
+// bridge only activates inside an iframe when ?cms-preview=1 is present.
+//
+// Protocol is versioned and mirrored in ab-cms (src/lib/preview-protocol.ts);
+// keep the two in sync when it changes.
+export const PREVIEW_PROTOCOL_VERSION = 1;
+export const PREVIEW_QUERY_FLAG = "cms-preview";
+/** Type guard + version check for messages arriving from the dashboard. */
+export function parseInbound(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const m = data;
+    if (m.source !== "ab-cms-dashboard" || m.v !== PREVIEW_PROTOCOL_VERSION)
+        return null;
+    if (m.type === "scroll-to-section" && typeof m.title === "string") {
+        return { source: "ab-cms-dashboard", v: PREVIEW_PROTOCOL_VERSION, type: "scroll-to-section", title: m.title };
+    }
+    if (m.type === "refresh") {
+        return { source: "ab-cms-dashboard", v: PREVIEW_PROTOCOL_VERSION, type: "refresh" };
+    }
+    return null;
+}
+export function readyMessage(sections) {
+    return { source: "ab-cms-preview", v: PREVIEW_PROTOCOL_VERSION, type: "ready", sections };
+}
+export function sectionClickedMessage(title) {
+    return { source: "ab-cms-preview", v: PREVIEW_PROTOCOL_VERSION, type: "section-clicked", title };
+}
+export function editItemMessage(id) {
+    return { source: "ab-cms-preview", v: PREVIEW_PROTOCOL_VERSION, type: "edit-item", id };
+}
+// The portal's current host and the one it moves to (rebrand, 2026-10). Keep
+// the abdevpanel origins until no site runs an SDK that predates the move.
+// The "ab-cms-*" message sources below are the wire protocol, not branding:
+// renaming them would break preview against every installed SDK version.
+const DEFAULT_ORIGINS = [
+    "https://www.abdevpanel.com",
+    "https://abdevpanel.com",
+    "https://app.abdevpanel.com",
+    "https://app.fullgrainsoftware.com",
+];
+function isPreviewContext(allowed) {
+    if (typeof window === "undefined")
+        return false;
+    if (window.parent === window)
+        return false; // not framed
+    try {
+        if (!new URLSearchParams(window.location.search).has(PREVIEW_QUERY_FLAG))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    // The whole bridge (including the capturing click listener that suppresses
+    // default actions) activates here, so make this gate at least as strong as
+    // the postMessage origin checks. Where the browser exposes the embedder
+    // origin, require it to be trusted; browsers without ancestorOrigins (e.g.
+    // Firefox) fall back to the framed + query-flag check.
+    const ancestors = window.location
+        .ancestorOrigins;
+    if (ancestors && ancestors.length > 0) {
+        return allowed.includes(ancestors[0]);
+    }
+    return true;
+}
+function collectSectionTitles() {
+    const nodes = document.querySelectorAll("[data-cms-section]");
+    const titles = [];
+    nodes.forEach((n) => {
+        const t = n.dataset.cmsSection?.trim();
+        if (t && !titles.includes(t))
+            titles.push(t);
+    });
+    return titles;
+}
+function findSection(title) {
+    const target = title.trim().toLowerCase();
+    const nodes = document.querySelectorAll("[data-cms-section]");
+    for (const n of nodes) {
+        if (n.dataset.cmsSection?.trim().toLowerCase() === target)
+            return n;
+    }
+    return null;
+}
+/**
+ * Activate the preview bridge. Safe to call unconditionally: it no-ops on the
+ * server and on the public (non-preview) site. Returns a cleanup function.
+ */
+export function initCmsPreview(options = {}) {
+    const allowed = options.allowedOrigins?.length ? options.allowedOrigins : DEFAULT_ORIGINS;
+    if (!isPreviewContext(allowed))
+        return () => { };
+    const post = (msg) => {
+        for (const origin of allowed) {
+            try {
+                window.parent.postMessage(msg, origin);
+            }
+            catch {
+                // origin not the real parent; ignore
+            }
+        }
+    };
+    const announce = () => post(readyMessage(collectSectionTitles()));
+    const onMessage = (event) => {
+        if (!allowed.includes(event.origin))
+            return;
+        const msg = parseInbound(event.data);
+        if (!msg)
+            return;
+        if (msg.type === "refresh") {
+            window.location.reload();
+            return;
+        }
+        if (msg.type === "scroll-to-section") {
+            const el = findSection(msg.title);
+            if (!el)
+                return;
+            el.scrollIntoView({ behavior: "smooth", block: "start" });
+            el.classList.add("cms-preview-flash");
+            window.setTimeout(() => el.classList.remove("cms-preview-flash"), 1600);
+        }
+    };
+    const onClick = (event) => {
+        const target = event.target;
+        // An editable item (a testimonial, a gallery card) takes priority: it opens
+        // that item's editor. Otherwise a tagged section just selects in the editor.
+        const item = target?.closest("[data-cms-editable][data-cms-item]");
+        const itemId = item?.dataset.cmsItem?.trim();
+        if (itemId) {
+            // In preview a click edits the item; don't follow the item's own link.
+            event.preventDefault();
+            event.stopPropagation();
+            post(editItemMessage(itemId));
+            return;
+        }
+        const section = target?.closest("[data-cms-section]");
+        const title = section?.dataset.cmsSection?.trim();
+        if (title)
+            post(sectionClickedMessage(title));
+    };
+    // A minimal highlight style, injected once, so sites need no extra CSS.
+    const style = document.createElement("style");
+    style.dataset.cmsPreview = "";
+    style.textContent =
+        ".cms-preview-flash{animation:cms-preview-flash 1.6s ease-out}" +
+            "@keyframes cms-preview-flash{0%{box-shadow:inset 0 0 0 3px rgba(139,147,255,.9)}100%{box-shadow:inset 0 0 0 0 transparent}}";
+    document.head.appendChild(style);
+    window.addEventListener("message", onMessage);
+    document.addEventListener("click", onClick, true);
+    if (document.readyState === "complete")
+        announce();
+    else
+        window.addEventListener("load", announce, { once: true });
+    return () => {
+        window.removeEventListener("message", onMessage);
+        document.removeEventListener("click", onClick, true);
+        style.remove();
+    };
+}

package/dist/reader.d.ts

@@ -0,0 +1,23 @@
+import type { SiteManifest } from "./manifest.js";
+import type { CMSWebsite } from "./cms-types.js";
+/** Per-item CMS metadata for click-to-edit. `id` is the section-group id, or
+ *  "" when the item comes from the manifest seed (nothing to edit yet). */
+export type CmsItemMeta = {
+    _cms: {
+        id: string;
+    };
+};
+export type SiteContent<T extends SiteManifest> = {
+    [S in T["pages"][number]["sections"][number] as S["key"]]: S["kind"] extends "repeatable" ? Array<{
+        [K in keyof S["fields"]]: string;
+    } & CmsItemMeta> : {
+        [K in keyof S["fields"]]: string;
+    } & CmsItemMeta;
+};
+export declare function readSiteContent<T extends SiteManifest>(manifest: T, website: CMSWebsite | null | undefined): SiteContent<T>;
+/**
+ * Spread onto an item's wrapper element to make it click-to-edit in the
+ * dashboard preview: `<div {...cmsItemProps(item)}>`. Returns {} for seed items
+ * (no CMS id yet), leaving them non-editable.
+ */
+export declare function cmsItemProps(item: CmsItemMeta): Record<string, string>;