@the-portland-company/canvas-editor 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+Initial extraction of the shared VRM Canvas Editor substrate from the V1 email
+canvas (`politogy-email`), per Ben Edtl's canvas-editor handoff (2026-09-10).
+
+- **Document model** (`CanvasDocument`, `Block`, `BlockType`, `EmailSettings`)
+  and block registry (`BLOCK_LIBRARY`, `BlockDefinition`) — extracted verbatim.
+- **Renderer** (`renderEmailHtml` / `renderEmailText` / `pinBlockSchemaVersion`)
+  on the server-safe root and `/renderer` subpaths.
+- **Editor surface** (`<CanvasEditor>`) on the `"use client"` `/editor` subpath:
+  palette, canvas, selection, inline text toolbar, hover-`+` insert, per-block
+  properties with padding + mobile overrides, Desktop/Mobile/Dark preview,
+  media library, template picker, autosave with conflict detection, footer
+  (CAN-SPAM) block.
+- **Adapter boundary** (`CanvasHostAdapter`): persistence, preview, send-test,
+  templates, media, personalization tokens, brand — injected by the host. The
+  package imports no `next/*`, `@supabase/*`, or app code.
+- Host-specific metadata (email subject/preheader + deliverability panel) moved
+  out of the package into a host `metaPanel` slot; carried opaquely in the
+  document `meta` bag.
+- React 18 || 19 peer; `@dnd-kit` and `vrm-builder` (skeletons) as peers.
+- 66 CORE parity unit tests ported from the email app — all passing.

package/README.md

@@ -0,0 +1,107 @@
+# @the-portland-company/canvas-editor
+
+The shared **VRM Canvas Editor** substrate for Politogy VRM apps: one block/layout
+document model, one block registry, one HTML renderer, and one drag-and-drop
+editor surface. Every module that needs canvas editing (Email, and later Forms,
+Surveys, CTAs, landing pages) binds to this package and registers its own blocks
+— nobody rebuilds the editor.
+
+Framework-agnostic by construction: the package **never imports `next/*`,
+`@supabase/*`, `@the-portland-company/shell`, or any app code**. All persistence,
+media, templates, brand tokens, and merge-field resolution are injected by the
+host through a single `CanvasHostAdapter`. It runs in a Next.js (React 19) app
+and a Vite (React 18) app alike.
+
+> Extracted verbatim from the V1 email canvas (`politogy-email`) so behavior is
+> identical. See the audit in `politogy-email/CANVAS_EDITOR_AUDIT.md`.
+
+## Entry points
+
+| Import | Contents | Environment |
+| --- | --- | --- |
+| `@the-portland-company/canvas-editor` | Document model, block registry, tree ops, HTML renderer, adapter **types** | **Server-safe** — pure logic, no React, no `@dnd-kit`. Import from Server Components / server actions / API routes. |
+| `@the-portland-company/canvas-editor/editor` | `<CanvasEditor>` + hooks | **`"use client"`** — pulls `@dnd-kit`. Client only. |
+| `@the-portland-company/canvas-editor/renderer` | `renderEmailHtml` / `renderEmailText` / `pinBlockSchemaVersion` | Server-safe. |
+| `@the-portland-company/canvas-editor/skeletons` | `Skeleton` / `SkeletonBar` (self-contained, token-driven) | Server-renderable. |
+| `@the-portland-company/canvas-editor/css` | Primitive component classes (`.card`/`.input`/`.btn`/`.skeleton`…) | Import once in the app. |
+
+**Never import `/editor` from a server module** — `@dnd-kit` evaluates
+`React.createContext` at module load and will crash in an RSC / server-action
+context. Server code that needs block logic imports the root (`.`) only.
+
+## Consuming it
+
+1. **Install** from the registry (never `npm link`; use `npm pack` tarballs for
+   local dev against an unpublished change):
+   ```
+   npm i @the-portland-company/canvas-editor
+   ```
+
+2. **Tailwind `@source`** — the editor ships as Tailwind utility classes in
+   `dist`, and Tailwind v4 does not scan `node_modules`. Add to your
+   `app/globals.css` or it renders unstyled (silent — builds green, diagnose
+   against the live DOM):
+   ```css
+   @source "../node_modules/@the-portland-company/canvas-editor/dist";
+   ```
+
+3. **CSS + brand tokens** — import the primitive CSS, and make sure your app
+   already loads the runtime brand-tokens `<link>` (shell requirement). The
+   package paints only through `var(--token, fallback)`; colors and fonts come
+   from the app's runtime tokens, and dark mode flips automatically under your
+   app's `.dark` ancestor. The package defines **no** tokens.
+   ```ts
+   import "@the-portland-company/canvas-editor/css";
+   ```
+
+4. **Implement the adapter** and render the editor:
+   ```tsx
+   "use client";
+   import { CanvasEditor } from "@the-portland-company/canvas-editor/editor";
+   import type { CanvasHostAdapter } from "@the-portland-company/canvas-editor";
+
+   const adapter: CanvasHostAdapter = {
+     save: (id, doc, expectedUpdatedAt) => myServerActions.save(id, doc, expectedUpdatedAt),
+     renderPreview: (id, doc, opts) => myServerActions.renderPreview(id, doc, opts),
+     sendTest: (id, addrs) => myServerActions.sendTest(id, addrs),
+     templates: { list, loadInto, saveAs, resetToBlank },
+     media: { list, upload, updateAltText, delete: del, usageCount, trackUsage },
+     personalizationTokens: () => myServerActions.tokens(),
+     brand: () => myServerActions.brand(),
+   };
+
+   <CanvasEditor
+     adapter={adapter}
+     documentId={id}
+     initialDocument={{ name, blocks, settings, meta: { subject, preheader } }}
+     initialUpdatedAt={updatedAt}
+     nextAction={{ label: "Next: Sender →", href: senderHref }}
+     metaPanel={({ doc, setMeta }) => <MyEmailMetaPanel doc={doc} setMeta={setMeta} />}
+   />
+   ```
+
+## The boundary
+
+- **The package owns:** the document model (`CanvasDocument` = `name` + `blocks`
+  + `settings` + opaque `meta`), the block registry (core blocks pre-registered),
+  the editor UI (palette, canvas, selection, inline toolbar, insert model,
+  properties panel, mobile overrides, preview modes, autosave), and the renderer.
+- **The host supplies** (via `CanvasHostAdapter`): persistence, server-rendered
+  preview, send-test, templates, media library, personalization tokens, and
+  brand info. Host-specific fields (e.g. an email's subject/preheader and its
+  deliverability panel) live in the host and mount into the editor through the
+  `metaPanel` slot — they are carried in the document's opaque `meta` bag, which
+  the package never interprets.
+- **Merge-field / UVP resolution stays in the host adapter** — provenance and
+  exposure are enforced at the host's data layer, never in this package.
+
+## Development
+
+```
+npm run type-check   # tsc --noEmit
+npm test             # vitest (CORE parity tests ported from the email app)
+npm run build        # tsup dual-build + re-assert "use client" on the editor entry
+```
+
+Publishing is a tag-driven CI lane (`v*` tag → npm). `prepublishOnly` runs
+type-check + `npm audit --audit-level=high` + tests + build.

package/dist/adapters-C5K7Ttha.d.ts

@@ -0,0 +1,131 @@
+import { C as CanvasDocument, B as Block } from './types-DJm_CBQt.js';
+
+/** A media asset the editor can place. Mirrors the host's media row, trimmed to
+ *  what the editor needs. */
+type MediaAsset = {
+    id: string;
+    url: string;
+    content_type: string;
+    filename: string;
+    size_bytes: number;
+    alt_text: string | null;
+};
+/** A template the host offers in the Load Template picker. Carries `blocks` so
+ *  the picker can render a live thumbnail, and `created_at` for the date label. */
+type TemplateSummary = {
+    id: string;
+    name: string;
+    category: string | null;
+    is_curated: boolean;
+    blocks: Block[];
+    created_at: string;
+};
+/** Media list + the account's storage quota (host-specific), for the readout. */
+type MediaListResult = {
+    assets: MediaAsset[];
+    quota: {
+        usedBytes: number;
+        quotaBytes: number;
+    } | null;
+};
+/** A personalization/merge token the host exposes. The host decides which tokens
+ *  exist and is solely responsible for resolving them against its data at
+ *  send/preview time (provenance + exposure enforced in the host, never here). */
+type PersonalizationToken = {
+    token: string;
+    label: string;
+};
+/** A brand swatch surfaced in color pickers. */
+type PaletteSwatch = {
+    label: string;
+    hex: string;
+};
+/** Brand context the editor reflects (colors + body font). `available:false`
+ *  lets the UI show an honest "brand not loaded" note instead of fabricating. */
+type BrandInfo = {
+    swatches: PaletteSwatch[];
+    fontFamily: string | null;
+    available: boolean;
+};
+type SaveResult = {
+    ok: true;
+    updatedAt: string;
+    document: CanvasDocument;
+} | {
+    ok: false;
+    conflict: true;
+    current: CanvasDocument;
+    updatedAt: string;
+} | {
+    ok: false;
+    conflict: false;
+    error: string;
+};
+type SendTestResult = {
+    ok: true;
+} | {
+    ok: false;
+    unavailable: true;
+    error: string;
+} | {
+    ok: false;
+    unavailable: false;
+    error: string;
+};
+type UploadMediaResult = {
+    ok: true;
+    assetId: string;
+    url: string;
+    contentType: string;
+    filename: string;
+} | {
+    ok: false;
+    error: string;
+};
+type SimpleResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+type RenderedPreview = {
+    html: string;
+    text: string;
+};
+interface CanvasHostAdapter {
+    /** Persist the document. The editor autosaves on a debounce and passes the
+     *  `updated_at` it last saw for conflict-safety (never a hard overwrite). */
+    save(documentId: string, doc: CanvasDocument, expectedUpdatedAt: string): Promise<SaveResult>;
+    /** Server-rendered preview HTML/text (host injects account context: physical
+     *  address, unsubscribe URL, brand font). Keeps merge-field/UVP resolution in
+     *  the host. */
+    renderPreview(documentId: string, doc: CanvasDocument, opts?: {
+        darkMode?: boolean;
+    }): Promise<RenderedPreview>;
+    /** Send a test to the given addresses. `unavailable:true` distinguishes a
+     *  provider/credits outage from a validation error. */
+    sendTest(documentId: string, addresses: string[]): Promise<SendTestResult>;
+    templates: {
+        list(): Promise<TemplateSummary[]>;
+        loadInto(documentId: string, templateId: string): Promise<SaveResult>;
+        saveAs(documentId: string, name: string): Promise<SimpleResult>;
+        resetToBlank(documentId: string): Promise<SaveResult>;
+    };
+    media: {
+        list(search?: string): Promise<MediaListResult>;
+        upload(file: File): Promise<UploadMediaResult>;
+        updateAltText(assetId: string, altText: string): Promise<SimpleResult>;
+        delete(assetId: string): Promise<SimpleResult>;
+        usageCount(assetId: string): Promise<number>;
+        trackUsage(assetId: string, documentId: string): Promise<void>;
+    };
+    /** Tokens the host exposes for insertion; host resolves them at render time. */
+    personalizationTokens(): Promise<PersonalizationToken[]>;
+    /** Brand colors + body font for the active org, consumed live. */
+    brand(): Promise<BrandInfo>;
+}
+/** Default personalization tokens (the V1 email set) — a host may return these
+ *  verbatim from `personalizationTokens()` or supply its own. */
+declare const DEFAULT_PERSONALIZATION_TOKENS: PersonalizationToken[];
+
+export { type BrandInfo as B, type CanvasHostAdapter as C, DEFAULT_PERSONALIZATION_TOKENS as D, type MediaAsset as M, type PersonalizationToken as P, type RenderedPreview as R, type SaveResult as S, type TemplateSummary as T, type UploadMediaResult as U, type MediaListResult as a, type PaletteSwatch as b, type SendTestResult as c, type SimpleResult as d };

package/dist/adapters-DvBAf0cj.d.cts

@@ -0,0 +1,131 @@
+import { C as CanvasDocument, B as Block } from './types-DJm_CBQt.cjs';
+
+/** A media asset the editor can place. Mirrors the host's media row, trimmed to
+ *  what the editor needs. */
+type MediaAsset = {
+    id: string;
+    url: string;
+    content_type: string;
+    filename: string;
+    size_bytes: number;
+    alt_text: string | null;
+};
+/** A template the host offers in the Load Template picker. Carries `blocks` so
+ *  the picker can render a live thumbnail, and `created_at` for the date label. */
+type TemplateSummary = {
+    id: string;
+    name: string;
+    category: string | null;
+    is_curated: boolean;
+    blocks: Block[];
+    created_at: string;
+};
+/** Media list + the account's storage quota (host-specific), for the readout. */
+type MediaListResult = {
+    assets: MediaAsset[];
+    quota: {
+        usedBytes: number;
+        quotaBytes: number;
+    } | null;
+};
+/** A personalization/merge token the host exposes. The host decides which tokens
+ *  exist and is solely responsible for resolving them against its data at
+ *  send/preview time (provenance + exposure enforced in the host, never here). */
+type PersonalizationToken = {
+    token: string;
+    label: string;
+};
+/** A brand swatch surfaced in color pickers. */
+type PaletteSwatch = {
+    label: string;
+    hex: string;
+};
+/** Brand context the editor reflects (colors + body font). `available:false`
+ *  lets the UI show an honest "brand not loaded" note instead of fabricating. */
+type BrandInfo = {
+    swatches: PaletteSwatch[];
+    fontFamily: string | null;
+    available: boolean;
+};
+type SaveResult = {
+    ok: true;
+    updatedAt: string;
+    document: CanvasDocument;
+} | {
+    ok: false;
+    conflict: true;
+    current: CanvasDocument;
+    updatedAt: string;
+} | {
+    ok: false;
+    conflict: false;
+    error: string;
+};
+type SendTestResult = {
+    ok: true;
+} | {
+    ok: false;
+    unavailable: true;
+    error: string;
+} | {
+    ok: false;
+    unavailable: false;
+    error: string;
+};
+type UploadMediaResult = {
+    ok: true;
+    assetId: string;
+    url: string;
+    contentType: string;
+    filename: string;
+} | {
+    ok: false;
+    error: string;
+};
+type SimpleResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+type RenderedPreview = {
+    html: string;
+    text: string;
+};
+interface CanvasHostAdapter {
+    /** Persist the document. The editor autosaves on a debounce and passes the
+     *  `updated_at` it last saw for conflict-safety (never a hard overwrite). */
+    save(documentId: string, doc: CanvasDocument, expectedUpdatedAt: string): Promise<SaveResult>;
+    /** Server-rendered preview HTML/text (host injects account context: physical
+     *  address, unsubscribe URL, brand font). Keeps merge-field/UVP resolution in
+     *  the host. */
+    renderPreview(documentId: string, doc: CanvasDocument, opts?: {
+        darkMode?: boolean;
+    }): Promise<RenderedPreview>;
+    /** Send a test to the given addresses. `unavailable:true` distinguishes a
+     *  provider/credits outage from a validation error. */
+    sendTest(documentId: string, addresses: string[]): Promise<SendTestResult>;
+    templates: {
+        list(): Promise<TemplateSummary[]>;
+        loadInto(documentId: string, templateId: string): Promise<SaveResult>;
+        saveAs(documentId: string, name: string): Promise<SimpleResult>;
+        resetToBlank(documentId: string): Promise<SaveResult>;
+    };
+    media: {
+        list(search?: string): Promise<MediaListResult>;
+        upload(file: File): Promise<UploadMediaResult>;
+        updateAltText(assetId: string, altText: string): Promise<SimpleResult>;
+        delete(assetId: string): Promise<SimpleResult>;
+        usageCount(assetId: string): Promise<number>;
+        trackUsage(assetId: string, documentId: string): Promise<void>;
+    };
+    /** Tokens the host exposes for insertion; host resolves them at render time. */
+    personalizationTokens(): Promise<PersonalizationToken[]>;
+    /** Brand colors + body font for the active org, consumed live. */
+    brand(): Promise<BrandInfo>;
+}
+/** Default personalization tokens (the V1 email set) — a host may return these
+ *  verbatim from `personalizationTokens()` or supply its own. */
+declare const DEFAULT_PERSONALIZATION_TOKENS: PersonalizationToken[];
+
+export { type BrandInfo as B, type CanvasHostAdapter as C, DEFAULT_PERSONALIZATION_TOKENS as D, type MediaAsset as M, type PersonalizationToken as P, type RenderedPreview as R, type SaveResult as S, type TemplateSummary as T, type UploadMediaResult as U, type MediaListResult as a, type PaletteSwatch as b, type SendTestResult as c, type SimpleResult as d };

package/dist/canvas.css

@@ -0,0 +1,67 @@
+/* Canvas Editor component classes — token-driven primitives extracted from V1 email app.
+   These classes are the base design-system components used by canvas-editor components.
+   All colors/fonts reference CSS custom properties (--color-*, --font-family) provided
+   at runtime by the consuming app's brand tokens. Dark mode is inherited from the app's
+   .dark ancestor class (not a media query), so dark theming "just works" when the app's
+   token values flip. */
+
+@keyframes shimmer { 0% { background-position: -200% 0; } 100% { background-position: 200% 0; } }
+.skeleton {
+  display: inline-block;
+  border-radius: 4px;
+  background: linear-gradient(90deg, var(--color-surface-2) 25%, var(--color-border) 37%, var(--color-surface-2) 63%);
+  background-size: 200% 100%;
+  animation: shimmer 1.4s ease-in-out infinite;
+  color: transparent !important;
+}
+
+.card {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow-sm);
+}
+
+.btn {
+  display: inline-flex; align-items: center; justify-content: center; gap: 0.375rem;
+  height: 2.25rem; padding: 0 0.85rem; border-radius: 0.375rem;
+  font-size: 0.85rem; font-weight: 500; cursor: pointer;
+  border: 1px solid var(--color-border); background: var(--color-surface); color: var(--color-text);
+  transition: background 0.12s, border-color 0.12s;
+}
+
+.btn:hover { background: var(--color-surface-2); }
+
+.btn:disabled { opacity: 0.5; cursor: not-allowed; }
+
+.btn-primary { background: var(--color-accent); border-color: var(--color-accent); color: #fff; }
+
+.btn-primary:hover { background: var(--color-accent-hover); }
+
+.btn-danger { background: color-mix(in srgb, var(--color-red) 90%, black); border-color: var(--color-red); color: #fff; }
+
+.btn-sm { height: 1.85rem; padding: 0 0.6rem; font-size: 0.78rem; }
+
+.input, .textarea, .select {
+  width: 100%; background: var(--color-surface); color: var(--color-text);
+  border: 1px solid var(--color-border); border-radius: 0.375rem;
+  padding: 0.5rem 0.65rem; font-size: 0.875rem;
+}
+
+.textarea { resize: vertical; min-height: 6rem; line-height: 1.5; }
+
+.input:focus, .textarea:focus, .select:focus { outline: 2px solid color-mix(in srgb, var(--color-accent) 40%, transparent); outline-offset: 0; border-color: var(--color-accent); }
+
+.label { font-size: 0.78rem; font-weight: 600; color: var(--color-text-muted); margin-bottom: 0.25rem; display: block; }
+
+.muted { color: var(--color-text-muted); }
+
+.pill { display: inline-flex; align-items: center; gap: 0.3rem; font-size: 0.72rem; font-weight: 600; padding: 0.12rem 0.5rem; border-radius: 999px; white-space: nowrap; }
+
+.chip { display: inline-flex; align-items: center; gap: 0.25rem; font-size: 0.7rem; font-weight: 600; padding: 0.1rem 0.4rem; border-radius: 4px; background: var(--color-surface-2); color: var(--color-text-muted); }
+
+.phone-frame {
+  width: 100%; max-width: 20rem; margin: 0 auto;
+  border: 8px solid var(--color-border); border-radius: 2rem;
+  background: var(--color-surface-2); padding: 1rem 0.75rem; min-height: 12rem;
+}