@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/apps/client-cms-editor/frontend/src/editor/useCmsEditorController.ts

@@ -0,0 +1,218 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type { CmsEditorAdapter } from '../../../shared/cms/src/adapter';
+import type {
+  CmsEditorBlock,
+  CmsEditorPage,
+  CmsEditorSection,
+  CmsEditorSite,
+} from '../../../shared/cms/src/editor-types';
+import type { CmsEditorHost } from '../../../shared/cms/src/host';
+import type { CmsPublicationSnapshot, CmsRevision } from '../../../shared/cms/src/adapter';
+
+export type CmsEditorUiState = {
+  rail: 'pages' | 'sections' | 'blocks' | 'media' | 'settings';
+  viewport: 'phone' | 'tablet' | 'desktop';
+  dirty: boolean;
+  saving: boolean;
+  publishing: boolean;
+  error: string | null;
+  temporaryAdapterNotice: string | null;
+};
+
+export type CmsEditorController = {
+  adapter: CmsEditorAdapter;
+  host?: CmsEditorHost;
+  site: CmsEditorSite | null;
+  page: CmsEditorPage | null;
+  section: CmsEditorSection | null;
+  block: CmsEditorBlock | null;
+  ui: CmsEditorUiState;
+  published: CmsPublicationSnapshot | null;
+  lastDraft: CmsRevision | null;
+  selectPage: (pageId: string) => void;
+  selectSection: (sectionId: string) => void;
+  selectBlock: (blockId: string) => void;
+  setRail: (rail: CmsEditorUiState['rail']) => void;
+  setViewport: (viewport: CmsEditorUiState['viewport']) => void;
+  updateSectionField: (key: string, value: unknown) => void;
+  saveDraft: () => Promise<void>;
+  publish: () => Promise<void>;
+  reload: () => Promise<void>;
+  navigateHost: (path: string) => void;
+};
+
+export type UseCmsEditorControllerArgs = {
+  adapter: CmsEditorAdapter;
+  host?: CmsEditorHost;
+  siteId: string;
+  initialPageId?: string | null;
+  initialRail?: CmsEditorUiState['rail'];
+  temporaryAdapter?: boolean;
+};
+
+export function useCmsEditorController({
+  adapter,
+  host,
+  siteId,
+  initialPageId = null,
+  initialRail = 'sections',
+  temporaryAdapter = false,
+}: UseCmsEditorControllerArgs): CmsEditorController {
+  const [site, setSite] = useState<CmsEditorSite | null>(null);
+  const [pageId, setPageId] = useState<string | null>(initialPageId);
+  const [sectionId, setSectionId] = useState<string | null>(null);
+  const [blockId, setBlockId] = useState<string | null>(null);
+  const [published, setPublished] = useState<CmsPublicationSnapshot | null>(null);
+  const [lastDraft, setLastDraft] = useState<CmsRevision | null>(null);
+  const [ui, setUi] = useState<CmsEditorUiState>({
+    rail: initialRail,
+    viewport: 'desktop',
+    dirty: false,
+    saving: false,
+    publishing: false,
+    error: null,
+    temporaryAdapterNotice: temporaryAdapter
+      ? 'Temporary adapter · changes are not durable until a SQLite/D1/HTTP adapter is attached. Starter pack content is real product content.'
+      : null,
+  });
+
+  const reload = useCallback(async () => {
+    setUi((u) => ({ ...u, error: null }));
+    const loaded = await adapter.loadSite(siteId);
+    setSite(loaded);
+    const page =
+      loaded.pages.find((p) => p.id === initialPageId) ||
+      loaded.pages.find((p) => p.id === pageId) ||
+      loaded.pages[0] ||
+      null;
+    setPageId(page?.id || null);
+    setSectionId(page?.sections[0]?.id || null);
+    setBlockId(null);
+    setUi((u) => ({ ...u, dirty: false }));
+    if (page?.id) {
+      const pub = await adapter.getPublishedRevision(page.id);
+      setPublished(pub);
+    }
+  }, [adapter, siteId, initialPageId, pageId]);
+
+  useEffect(() => {
+    reload().catch((error) => {
+      setUi((u) => ({ ...u, error: error?.message || String(error) }));
+      setSite(null);
+    });
+    // intentionally load once per site/adapter
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [adapter, siteId]);
+
+  const page = useMemo(
+    () => site?.pages.find((p) => p.id === pageId) || site?.pages[0] || null,
+    [site, pageId],
+  );
+  const section = useMemo(
+    () => page?.sections.find((s) => s.id === sectionId) || page?.sections[0] || null,
+    [page, sectionId],
+  );
+  const block = useMemo(
+    () => section?.blocks.find((b) => b.id === blockId) || null,
+    [section, blockId],
+  );
+
+  const selectPage = useCallback((id: string) => {
+    setPageId(id);
+    setSectionId(null);
+    setBlockId(null);
+    setUi((u) => ({ ...u, dirty: false, rail: 'sections' }));
+  }, []);
+
+  const selectSection = useCallback((id: string) => {
+    setSectionId(id);
+    setBlockId(null);
+    setUi((u) => ({ ...u, rail: 'sections' }));
+  }, []);
+
+  const selectBlock = useCallback((id: string) => {
+    setBlockId(id);
+    setUi((u) => ({ ...u, rail: 'blocks' }));
+  }, []);
+
+  const updateSectionField = useCallback(
+    (key: string, value: unknown) => {
+      if (!site || !page || !section) return;
+      setSite((current) => {
+        if (!current) return current;
+        return {
+          ...current,
+          pages: current.pages.map((p) =>
+            p.id !== page.id
+              ? p
+              : {
+                  ...p,
+                  sections: p.sections.map((s) =>
+                    s.id !== section.id ? s : { ...s, fields: { ...s.fields, [key]: value } },
+                  ),
+                },
+          ),
+        };
+      });
+      setUi((u) => ({ ...u, dirty: true }));
+    },
+    [site, page, section],
+  );
+
+  const saveDraft = useCallback(async () => {
+    if (!page) return;
+    setUi((u) => ({ ...u, saving: true, error: null }));
+    try {
+      const revision = await adapter.saveDraft(page.id, { sections: page.sections });
+      setLastDraft(revision);
+      setUi((u) => ({ ...u, dirty: false, saving: false }));
+    } catch (error: any) {
+      setUi((u) => ({ ...u, saving: false, error: error?.message || String(error) }));
+      throw error;
+    }
+  }, [adapter, page]);
+
+  const publish = useCallback(async () => {
+    if (!page) return;
+    setUi((u) => ({ ...u, publishing: true, error: null }));
+    try {
+      if (ui.dirty) await saveDraft();
+      const snapshot = await adapter.publish(page.id);
+      setPublished(snapshot);
+      await reload();
+      setUi((u) => ({ ...u, publishing: false, dirty: false }));
+    } catch (error: any) {
+      setUi((u) => ({ ...u, publishing: false, error: error?.message || String(error) }));
+      throw error;
+    }
+  }, [adapter, page, ui.dirty, saveDraft, reload]);
+
+  const navigateHost = useCallback(
+    (path: string) => {
+      if (host?.navigate) host.navigate(path);
+    },
+    [host],
+  );
+
+  return {
+    adapter,
+    host,
+    site,
+    page,
+    section,
+    block,
+    ui,
+    published,
+    lastDraft,
+    selectPage,
+    selectSection,
+    selectBlock,
+    setRail: (rail) => setUi((u) => ({ ...u, rail })),
+    setViewport: (viewport) => setUi((u) => ({ ...u, viewport })),
+    updateSectionField,
+    saveDraft,
+    publish,
+    reload,
+    navigateHost,
+  };
+}

package/apps/client-cms-editor/frontend/src/env.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+declare module '*.css?raw' {
+  const content: string;
+  export default content;
+}
+
+declare module '@inneranimalmedia/agentsam-cms-backend/routing' {
+  export function buildCmsHubPath(siteSlug?: string | null, basePath?: string): string;
+  export function buildCmsPath(options?: any, basePath?: string): string;
+  export function parseCmsRoute(pathname?: string, searchParams?: any, basePath?: string): any;
+  export function buildCmsEditorPath(options?: any, basePath?: string): string;
+}
+

package/apps/client-cms-editor/frontend/src/index.ts

@@ -0,0 +1,22 @@
+export { default as CmsEditor } from './editor/CmsEditor';
+export { default } from './editor/CmsEditor';
+export type { CmsEditorProps } from './editor/CmsEditor';
+export { mountClientCmsEditor, type ClientCmsEditorBoot } from './mount';
+export { CmsAgentSurface, type CmsAgentSurfaceProps } from './CmsAgentSurface';
+export { AgentSamDrawer, type AgentSamDrawerProps } from './AgentSamDrawer';
+export type { CmsAgentHost, CmsAnnotationSelection, CmsHostPrincipal } from './lib/agent-host';
+export { MemoryCmsAdapter } from './adapters/memory';
+export { HttpCmsAdapter, createHttpCmsAdapter } from './adapters/http';
+export { previewHeuristicStarter, createHeuristicThemeMemoryAdapter } from './adapters/heuristic';
+export { useCmsEditorController } from './editor/useCmsEditorController';
+export { useCmsEditor } from './editor/CmsEditorProvider';
+export {
+  heuristicStarterPack,
+  listBuiltinStarterPacks,
+  HEURISTIC_STARTER_PACK_ID,
+} from '../../starter-packs/heuristic';
+export { blankStarterPack, BLANK_STARTER_PACK_ID } from '../../starter-packs/blank';
+export { iasfStarterPack, IASF_STARTER_PACK_ID, listIasfStarterPacks } from '../../starter-packs/iasf';
+export { installStarterPack } from '../../shared/cms/src/starter-pack';
+export type { CmsStarterPack } from '../../shared/cms/src/starter-pack';
+export * from './surfaces/index';

package/apps/client-cms-editor/frontend/src/lib/agent-host.ts

@@ -0,0 +1,24 @@
+/**
+ * Optional AgentSam / workbench host slot (React render props).
+ * Defined in the frontend package so shared/cms stays React-free.
+ */
+import type { ReactNode } from 'react';
+import type {
+  CmsAgentDrawerSlotProps,
+  CmsAgentMiniSlotProps,
+  CmsHostPrincipal,
+} from '../../../shared/cms/src/host';
+
+export type CmsAgentHost = {
+  principal?: CmsHostPrincipal | null;
+  conversationId?: string;
+  renderDrawer?: (props: CmsAgentDrawerSlotProps) => ReactNode;
+  renderMini?: (props: CmsAgentMiniSlotProps) => ReactNode;
+};
+
+export type {
+  CmsAgentDrawerSlotProps,
+  CmsAgentMiniSlotProps,
+  CmsAnnotationSelection,
+  CmsHostPrincipal,
+} from '../../../shared/cms/src/host';

package/apps/client-cms-editor/frontend/src/lib/content-safety.ts

@@ -0,0 +1,63 @@
+const RICH_TAGS = new Set(['B', 'STRONG', 'I', 'EM', 'U', 'BR', 'P', 'UL', 'OL', 'LI', 'H2', 'H3', 'A']);
+
+export function escapeCmsText(value: unknown) {
+  return String(value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+export function safeCmsAssetUrl(value: unknown) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return '';
+  if (raw.startsWith('/') || raw.startsWith('./') || raw.startsWith('../') || raw.startsWith('blob:')) {
+    return raw.replaceAll("'", '%27').replace(/[\r\n]/g, '');
+  }
+  if (/^data:image\/(?:png|jpeg|jpg|gif|webp);/i.test(raw)) {
+    return raw.replaceAll("'", '%27').replace(/[\r\n]/g, '');
+  }
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return '';
+    return url.toString().replaceAll("'", '%27').replace(/[\r\n]/g, '');
+  } catch {
+    return '';
+  }
+}
+
+export function safeCmsCssValue(value: unknown) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return '';
+  if (/[{};]/.test(raw) || /<\/?(?:style|script)/i.test(raw) || /url\s*\(/i.test(raw)) return '';
+  return raw.replace(/[\r\n]/g, ' ');
+}
+
+export function sanitizeCmsRichText(value: unknown) {
+  const raw = String(value ?? '');
+  if (!raw) return '';
+  if (typeof DOMParser === 'undefined') return escapeCmsText(raw);
+
+  const doc = new DOMParser().parseFromString(`<body>${raw}</body>`, 'text/html');
+  const walk = (node: Element) => {
+    for (const child of Array.from(node.children)) {
+      if (!RICH_TAGS.has(child.tagName)) {
+        child.replaceWith(...Array.from(child.childNodes));
+        continue;
+      }
+      const originalHref = child.tagName === 'A' ? ((child as HTMLAnchorElement).getAttribute('href') || '') : '';
+      for (const attr of Array.from(child.attributes)) child.removeAttribute(attr.name);
+      if (child.tagName === 'A') {
+        const safe = safeCmsAssetUrl(originalHref);
+        if (safe) {
+          child.setAttribute('href', safe);
+          child.setAttribute('rel', 'noopener noreferrer');
+        }
+      }
+      walk(child);
+    }
+  };
+  walk(doc.body);
+  return doc.body.innerHTML;
+}

package/apps/client-cms-editor/frontend/src/main.tsx

@@ -0,0 +1,91 @@
+import { createRoot } from 'react-dom/client';
+import { StrictMode, useEffect, useState } from 'react';
+import CmsEditor from './editor/CmsEditor';
+import { previewHeuristicStarter } from './adapters/heuristic';
+import type { CmsEditorAdapter } from '../../shared/cms/src/adapter';
+import './styles/studio.css';
+
+const root = document.getElementById('root');
+if (!root) throw new Error('cms_studio_root_missing');
+
+const params = new URLSearchParams(window.location.search);
+const starter = (params.get('starter') || params.get('example') || '').trim();
+const siteParam = (params.get('site') || params.get('project') || '').trim();
+const pageId = (params.get('page') || '').trim() || null;
+
+function HeuristicBoot() {
+  const [state, setState] = useState<{
+    adapter: CmsEditorAdapter;
+    siteId: string;
+    pageId: string | null;
+  } | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    previewHeuristicStarter(siteParam || undefined)
+      .then((seeded) =>
+        setState({
+          adapter: seeded.adapter,
+          siteId: seeded.siteId,
+          pageId: pageId || seeded.pageId,
+        }),
+      )
+      .catch((err) => setError(err?.message || String(err)));
+  }, []);
+
+  if (error) {
+    return (
+      <main className="cms-shell cms-shell--error">
+        <h1>Starter install failed</h1>
+        <p>{error}</p>
+      </main>
+    );
+  }
+  if (!state) {
+    return (
+      <main className="cms-shell cms-shell--loading">
+        <p>Installing Heuristic starter into temporary adapter…</p>
+      </main>
+    );
+  }
+
+  return (
+    <CmsEditor
+      adapter={state.adapter}
+      siteId={state.siteId}
+      initialPageId={state.pageId}
+      temporaryAdapter
+    />
+  );
+}
+
+function boot() {
+  if (starter === 'heuristic' || starter === 'heuristic-theme') {
+    return <HeuristicBoot />;
+  }
+
+  if (!siteParam) {
+    return (
+      <main className="cms-shell cms-shell--error">
+        <h1>CMS site required</h1>
+        <p>
+          Pass <code>?site=your-site</code> with a host-provided CmsEditorAdapter, or start the
+          stock Heuristic pack with <code>?starter=heuristic</code> (temporary in-memory adapter
+          until a durable adapter is attached).
+        </p>
+      </main>
+    );
+  }
+
+  return (
+    <main className="cms-shell cms-shell--error">
+      <h1>CmsEditorAdapter required</h1>
+      <p>
+        Site <code>{siteParam}</code> needs a host-provided CmsEditorAdapter. This package does not
+        invent persistence from hostname or empty site ids.
+      </p>
+    </main>
+  );
+}
+
+createRoot(root).render(<StrictMode>{boot()}</StrictMode>);

package/apps/client-cms-editor/frontend/src/mount.tsx

@@ -0,0 +1,113 @@
+import { StrictMode, useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import CmsEditor from './editor/CmsEditor';
+import { previewHeuristicStarter } from './adapters/heuristic';
+import type { CmsEditorAdapter } from '../../shared/cms/src/adapter';
+
+export type ClientCmsEditorBoot = {
+  projectSlug: string;
+  pageId?: string | null;
+  panel?: 'pages' | 'sections' | 'templates' | 'imports' | 'theme';
+  /**
+   * Explicit stock starter. Never implied by localhost alone.
+   * Installs Heuristic into a temporary in-memory adapter for preview.
+   * Durable hosts should call installStarterPack(adapter, heuristicStarterPack) themselves.
+   */
+  starter?: 'heuristic';
+  /** @deprecated Use starter: 'heuristic' */
+  example?: 'heuristic-theme';
+};
+
+function HeuristicMount({
+  projectSlug,
+  pageId,
+  onSiteChange,
+}: {
+  projectSlug: string;
+  pageId?: string | null;
+  onSiteChange?: (slug: string) => void;
+}) {
+  const [state, setState] = useState<{
+    adapter: CmsEditorAdapter;
+    siteId: string;
+    pageId: string | null;
+  } | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    previewHeuristicStarter(projectSlug || undefined)
+      .then((seeded) => {
+        setState({
+          adapter: seeded.adapter,
+          siteId: seeded.siteId,
+          pageId: pageId || seeded.pageId,
+        });
+        onSiteChange?.(seeded.siteId);
+      })
+      .catch((err) => setError(err?.message || String(err)));
+  }, [projectSlug, pageId, onSiteChange]);
+
+  if (error) {
+    return (
+      <main className="cms-shell cms-shell--error">
+        <h1>Starter install failed</h1>
+        <p>{error}</p>
+      </main>
+    );
+  }
+  if (!state) {
+    return (
+      <main className="cms-shell cms-shell--loading">
+        <p>Installing Heuristic starter…</p>
+      </main>
+    );
+  }
+  return (
+    <CmsEditor
+      adapter={state.adapter}
+      siteId={state.siteId}
+      initialPageId={state.pageId}
+      temporaryAdapter
+    />
+  );
+}
+
+/**
+ * Imperative mount helper for hosts.
+ * Import styles separately:
+ *   import '@inneranimalmedia/client-cms-editor/styles/studio.css'
+ *
+ * Hosts should prefer passing their own CmsEditorAdapter + installStarterPack.
+ */
+export function mountClientCmsEditor(
+  mountEl: HTMLElement,
+  boot: ClientCmsEditorBoot,
+  onSiteChange?: (slug: string) => void,
+) {
+  if (boot.starter === 'heuristic' || boot.example === 'heuristic-theme') {
+    createRoot(mountEl).render(
+      <StrictMode>
+        <HeuristicMount
+          projectSlug={boot.projectSlug}
+          pageId={boot.pageId}
+          onSiteChange={onSiteChange}
+        />
+      </StrictMode>,
+    );
+    return;
+  }
+
+  createRoot(mountEl).render(
+    <StrictMode>
+      <main className="cms-shell cms-shell--error">
+        <h1>CmsEditorAdapter required</h1>
+        <p>
+          mountClientCmsEditor no longer invents persistence. Pass a host adapter via{' '}
+          <code>&lt;CmsEditor adapter=&#123;...&#125; /&gt;</code> and optionally{' '}
+          <code>installStarterPack(adapter, heuristicStarterPack)</code>, or set{' '}
+          <code>starter: &apos;heuristic&apos;</code> for an explicit temporary preview.
+        </p>
+      </main>
+    </StrictMode>,
+  );
+}