simple-module-pagebuilder 0.0.1__py3-none-any.whl

pagebuilder/service/_workflow.py

@@ -0,0 +1,207 @@
+"""Status transitions: publish, unpublish, schedule, submit, approve, reject.
+
+Mixed into :class:`~pagebuilder.service.PagesService`. Split out to keep each
+file focused; the methods are unchanged and still rely on ``self.db``,
+``self.get_page``, and ``self._record_revision`` from the composing class.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from fastapi import HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from pagebuilder.models import Page, PageStatus, RevisionEvent
+from pagebuilder.service._common import _UNSET, _normalize_to_utc, _Unset
+from pagebuilder.service._revisions import RevisionsMixin
+
+
+class WorkflowMixin(RevisionsMixin):
+    """Status-transition behaviour for :class:`PagesService`."""
+
+    db: AsyncSession
+
+    async def publish(self, page_id: int, note: str | None = None) -> Page:
+        page = await self.get_page(page_id)
+        page.published_data = page.draft_data
+        page.status = PageStatus.PUBLISHED
+        page.rejection_note = None
+        # A manual publish supersedes any pending auto-publish for the
+        # same page; clearing it stops the scheduler from re-firing on
+        # the next tick.
+        page.publish_at = None
+        self.db.add(page)
+        self._record_revision(page, event=RevisionEvent.PUBLISH, note=note)
+        await self.db.flush()
+        await self.db.refresh(page)
+        return page
+
+    async def unpublish(self, page_id: int, note: str | None = None) -> Page:
+        page = await self.get_page(page_id)
+        page.status = PageStatus.DRAFT
+        # Same reasoning as ``publish``: a manual unpublish wipes any
+        # pending auto-unpublish so the scheduler doesn't re-fire.
+        page.unpublish_at = None
+        self.db.add(page)
+        self._record_revision(page, event=RevisionEvent.UNPUBLISH, note=note)
+        await self.db.flush()
+        await self.db.refresh(page)
+        return page
+
+    async def schedule(
+        self,
+        page_id: int,
+        *,
+        publish_at: datetime | _Unset | None = _UNSET,
+        unpublish_at: datetime | _Unset | None = _UNSET,
+    ) -> Page:
+        """Set or clear a page's scheduled flip timestamps.
+
+        Each field is independently optional: pass a ``datetime`` to set,
+        pass ``None`` to clear, omit (sentinel ``_UNSET``) to leave the
+        existing value alone. Aware datetimes are normalized to UTC;
+        naive ones are assumed UTC. Rejects ``publish_at >= unpublish_at``
+        with a 422 since that would auto-unpublish before the auto-publish
+        could fire.
+        """
+        page = await self.get_page(page_id)
+        # Normalize both the incoming values and any already-stored values:
+        # SQLite drops tz info on round-trip, so a naive existing column
+        # would otherwise break the cross-field comparison below.
+        new_publish = (
+            _normalize_to_utc(publish_at)
+            if not isinstance(publish_at, _Unset)
+            else _normalize_to_utc(page.publish_at)
+        )
+        new_unpublish = (
+            _normalize_to_utc(unpublish_at)
+            if not isinstance(unpublish_at, _Unset)
+            else _normalize_to_utc(page.unpublish_at)
+        )
+        if (
+            new_publish is not None
+            and new_unpublish is not None
+            and new_publish >= new_unpublish
+        ):
+            raise HTTPException(
+                status_code=422,
+                detail="publish_at must be strictly before unpublish_at",
+            )
+        page.publish_at = new_publish
+        page.unpublish_at = new_unpublish
+        self.db.add(page)
+        await self.db.flush()
+        await self.db.refresh(page)
+        return page
+
+    async def process_due(self, now: datetime) -> list[Page]:
+        """Flip every page whose scheduled time has elapsed.
+
+        Drafts with ``publish_at <= now`` go live (clearing ``publish_at``);
+        published pages with ``unpublish_at <= now`` go back to draft
+        (clearing ``unpublish_at``). Returns the flipped pages so callers
+        can log / emit metrics.
+
+        Idempotent: each tick re-queries the table, so a missed wakeup
+        catches up on the next one. Failures on a single page are caught
+        and skipped so one bad row doesn't poison the whole tick.
+        """
+        flipped: list[Page] = []
+
+        pub_due = await self.db.execute(
+            select(Page).where(
+                Page.status == PageStatus.DRAFT,
+                Page.publish_at.is_not(None),  # type: ignore[union-attr]
+                Page.publish_at <= now,  # type: ignore[operator]
+            )
+        )
+        for page in pub_due.scalars().all():
+            try:
+                await self.publish(page.id or 0, note="Auto-published on schedule")
+                flipped.append(page)
+            except HTTPException:
+                continue
+
+        unpub_due = await self.db.execute(
+            select(Page).where(
+                Page.status == PageStatus.PUBLISHED,
+                Page.unpublish_at.is_not(None),  # type: ignore[union-attr]
+                Page.unpublish_at <= now,  # type: ignore[operator]
+            )
+        )
+        for page in unpub_due.scalars().all():
+            try:
+                await self.unpublish(page.id or 0, note="Auto-unpublished on schedule")
+                flipped.append(page)
+            except HTTPException:
+                continue
+
+        return flipped
+
+    async def submit_for_review(self, page_id: int, note: str | None = None) -> Page:
+        """Editor flow: hand a draft off to an approver.
+
+        Allowed transitions: ``DRAFT → SUBMITTED_FOR_REVIEW``. Re-submitting
+        an already-submitted page is a 409 — the approver still owns it.
+        Re-submission *after* a rejection is fine because the page was sent
+        back to ``DRAFT`` with a ``rejection_note`` that's now cleared.
+        """
+        page = await self.get_page(page_id)
+        if page.status != PageStatus.DRAFT:
+            raise HTTPException(
+                status_code=409,
+                detail=f"Cannot submit a page in '{page.status.value}' status",
+            )
+        page.status = PageStatus.SUBMITTED_FOR_REVIEW
+        page.rejection_note = None
+        self.db.add(page)
+        self._record_revision(page, event=RevisionEvent.SUBMIT, note=note)
+        await self.db.flush()
+        await self.db.refresh(page)
+        return page
+
+    async def approve(self, page_id: int, note: str | None = None) -> Page:
+        """Approver flow: take a submission live.
+
+        One audit row tagged ``APPROVE``; the row's ``data`` snapshot is
+        what ``/p/{slug}`` will serve, so it doubles as a restorable
+        revision the editor history offers alongside plain publishes.
+        """
+        page = await self.get_page(page_id)
+        if page.status != PageStatus.SUBMITTED_FOR_REVIEW:
+            raise HTTPException(
+                status_code=409,
+                detail=f"Cannot approve a page in '{page.status.value}' status",
+            )
+        page.published_data = page.draft_data
+        page.status = PageStatus.PUBLISHED
+        page.rejection_note = None
+        self.db.add(page)
+        self._record_revision(page, event=RevisionEvent.APPROVE, note=note)
+        await self.db.flush()
+        await self.db.refresh(page)
+        return page
+
+    async def reject(self, page_id: int, note: str) -> Page:
+        """Approver flow: send a submission back to draft with feedback.
+
+        ``note`` is captured on the page row (so the editor banner sees
+        the latest one without joining the revision table) *and* on the
+        revision row (so older notes stay queryable from the history).
+        """
+        page = await self.get_page(page_id)
+        if page.status != PageStatus.SUBMITTED_FOR_REVIEW:
+            raise HTTPException(
+                status_code=409,
+                detail=f"Cannot reject a page in '{page.status.value}' status",
+            )
+        page.status = PageStatus.DRAFT
+        page.rejection_note = note
+        self.db.add(page)
+        self._record_revision(page, event=RevisionEvent.REJECT, note=note)
+        await self.db.flush()
+        await self.db.refresh(page)
+        return page
+

pagebuilder/services.py

@@ -0,0 +1,19 @@
+"""Module-scoped state container.
+
+Stored as ``app.state.pagebuilder`` by
+:meth:`PagebuilderModule.register_settings`. Set once during boot,
+treat as read-only after.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pagebuilder.settings import PagebuilderSettings
+
+
+@dataclass
+class PagebuilderServices:
+    """PageBuilder module singletons."""
+
+    settings: PagebuilderSettings

pagebuilder/settings.py

@@ -0,0 +1,161 @@
+"""PageBuilder module settings.
+
+Per-module env-var prefix is ``SM_PAGEBUILDER_*``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class PagebuilderSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="SM_PAGEBUILDER_", extra="ignore")
+
+    public_route_prefix: str = "/p"
+    """URL prefix used for public published pages: ``{prefix}/{slug}``."""
+
+    media_root: Path = Path("var/pagebuilder/media")
+    """Filesystem directory where uploaded media is stored.
+
+    Resolved against the host's working directory on startup; created if
+    it doesn't exist.
+    """
+
+    media_url_prefix: str = "/media/pagebuilder"
+    """URL prefix the media directory is mounted at."""
+
+    media_max_bytes: int = 10 * 1024 * 1024
+    """Reject uploads larger than this (default 10 MB)."""
+
+    media_allowed_content_types: tuple[str, ...] = (
+        "image/jpeg",
+        "image/png",
+        "image/gif",
+        "image/webp",
+    )
+    """Content-types accepted by the upload endpoint.
+
+    SVG is intentionally excluded from the default allowlist: SVG is XML
+    and can embed ``<script>`` tags, yielding stored-XSS the moment a
+    user views the file under a same-origin URL. Hosts that need SVG
+    should add it explicitly via ``SM_PAGEBUILDER_MEDIA_ALLOWED_CONTENT_TYPES``
+    and pair it with their own sanitizer.
+    """
+
+    media_thumbnail_widths: tuple[int, ...] = (320, 640, 1280, 1920)
+    """Pixel widths to generate webp thumbnails for on upload.
+
+    Only widths *strictly less than* the source width produce a derivative
+    — there's no point upscaling a 600px hero to 1920px. Set to an empty
+    tuple to disable thumbnail generation entirely.
+    """
+
+    media_webp_quality: int = 82
+    """Pillow encoder ``quality`` for webp thumbnails (0-100)."""
+
+    public_csp: str = (
+        "default-src 'self'; "
+        "script-src 'self'; "
+        "style-src 'self' 'unsafe-inline'; "
+        "img-src 'self' https: data:; "
+        "font-src 'self' data:; "
+        "connect-src 'self'; "
+        "frame-ancestors 'none'; "
+        "base-uri 'self'; "
+        "form-action 'self'"
+    )
+    """Content-Security-Policy header value for ``/p/{slug}`` responses.
+
+    Override via ``SM_PAGEBUILDER_PUBLIC_CSP`` to widen for analytics,
+    fonts, CDNs, etc. Set to an empty string to disable.
+    """
+
+    public_cache_max_age: int = 60
+    """``max-age`` (seconds) on ``Cache-Control`` for published pages."""
+
+    public_cache_swr: int = 600
+    """``stale-while-revalidate`` (seconds) on published pages."""
+
+    public_base_url: str | None = None
+    """Absolute base URL of the public site (e.g. ``https://example.com``).
+
+    Used to build canonical / ``og:url`` values. When unset, the public
+    page falls back to ``Request.url`` — fine for local dev but unreliable
+    behind a reverse proxy that strips ``Host`` / ``X-Forwarded-*``
+    headers. No trailing slash; the public route prefix is appended.
+    """
+
+    site_name: str | None = None
+    """Brand name emitted as ``<meta property="og:site_name">``.
+
+    Skip the tag entirely when blank — empty meta tags hurt social-card
+    previews more than missing ones.
+    """
+
+    twitter_handle: str | None = None
+    """Publisher handle emitted as ``<meta name="twitter:site">``.
+
+    Include the leading ``@``; rendered verbatim so consumers (Twitter's
+    crawler, link unfurlers) see exactly what's configured. Skipped when
+    blank.
+    """
+
+    sitemap_enabled: bool = True
+    """Serve ``GET /sitemap.xml`` listing all published, indexable pages.
+
+    Disable when the host already publishes its own sitemap (e.g. a
+    multi-module deployment whose top-level sitemap aggregates several
+    sources).
+    """
+
+    robots_enabled: bool = True
+    """Serve ``GET /robots.txt`` referencing the sitemap when enabled."""
+
+    robots_body: str | None = None
+    """Override the default ``robots.txt`` body.
+
+    When ``None``, the route emits a minimal ``User-agent: *\nAllow: /``
+    plus a ``Sitemap:`` reference (only when ``sitemap_enabled``). Set
+    explicitly to lock crawlers out of a staging environment.
+    """
+
+    seo_cache_max_age: int = 300
+    """``max-age`` (seconds) on the ``Cache-Control`` header for
+    ``/sitemap.xml`` and ``/robots.txt``."""
+
+    requires_auth: bool = True
+    """Gate admin routes (``/pagebuilder/*`` and ``/api/pagebuilder/*``)
+    behind a ``get_current_user`` dependency.
+
+    Defaults to ``True`` so a host scaffolded without auth middleware does
+    not silently expose page CRUD + media uploads to the public internet.
+    The public viewer (``/p/{slug}``) is always anonymous regardless of
+    this setting. Disable via ``SM_PAGEBUILDER_REQUIRES_AUTH=false`` only
+    when the host gates admin paths at a layer above the application
+    (e.g. an authenticating reverse proxy).
+    """
+
+    csrf_protect: bool = True
+    """Require an ``X-CSRF-Token`` header on every mutating admin request.
+
+    The token is per-session, generated lazily on the first admin GET and
+    surfaced both via Inertia shared props (``csrf.token``) and a
+    non-``HttpOnly`` cookie (see ``csrf_cookie_name``) so the React client
+    can read it back and include it on every POST/PUT/PATCH/DELETE.
+    """
+
+    csrf_cookie_name: str = "pagebuilder_csrf"
+    """Cookie name used to expose the per-session CSRF token to JS."""
+
+    scheduler_enabled: bool = True
+    """Run an in-process loop that flips pages on their scheduled times.
+
+    Disable in deployments where a separate worker (Celery beat, k8s
+    CronJob, etc.) drives :meth:`PagesService.process_due` directly —
+    otherwise both would race and double-publish.
+    """
+
+    scheduler_interval_seconds: int = 30
+    """How often the in-process scheduler wakes to look for due flips."""

pagebuilder/static/widgets-base.css

@@ -0,0 +1,57 @@
+/* Base design tokens for the ported GCA widget set.
+ *
+ * The widgets read these through var(), so a site changes their whole look
+ * by overriding the tokens rather than by editing widget classes. A design
+ * pack (e.g. gca.css) layers over this.
+ */
+
+:root {
+	/* Page-builder (Puck widget) theme tokens — Recodo defaults. Tenants that
+	   need a different look (e.g. GCA in .gca-root) override these so the same
+	   widgets render per-tenant via the `style` property instead of hardcoded
+	   classes. */
+	--pb-display-weight: 300;
+	--pb-display-tracking: -0.025em;
+	--pb-display-font: var(--font-sans);
+	--pb-body-color: var(--muted-foreground);
+	--pb-heading-color: var(--foreground);
+	--pb-surface: var(--card);
+	--pb-surface-muted: var(--muted);
+	--pb-accent: var(--primary);
+	--pb-accent-foreground: var(--primary-foreground);
+	/* Text color on colored band surfaces (MediaObject/Faq/CallToAction
+	   surfaceColor, FeatureCards cardBg). */
+	--pb-surface-contrast: #ffffff;
+	/* CTA/Button pill shape + trailing arrow. `0.375rem` = the prior `rounded-md`;
+	   arrow is off by default (tenants set `inline-block` to reveal "→"). */
+	--pb-button-radius: 0.375rem;
+	--pb-button-arrow-display: none;
+	/* Section-eyebrow case/tracking is deliberately NOT defaulted here.
+	   `--pb-eyebrow-transform`/`--pb-eyebrow-tracking` are read only through
+	   `var(…, <fallback>)` in the widgets, and a var() fallback is skipped
+	   entirely once the property is set — so declaring `none`/`normal` globally
+	   made every call site's own fallback unreachable. That silently flattened
+	   the one call site whose previous literal was `uppercase tracking-wide`
+	   (Timeline "blobs"). The values here were byte-identical to
+	   EYEBROW_CASE_STYLE's fallbacks in _shared/mask.ts, so removing them
+	   changes nothing for the sentence-case eyebrows and lets each call site
+	   state its own prior literal. Tenants still override via their design pack. */
+	/* Hero geometry (consumed by the Hero/PageHeader widgets). */
+	--pb-hero-min-h: 560px;
+	--pb-hero-logo-max-h: 14rem;
+	--pb-hero-pull: 0px;
+}
+
+/* The public page wraps the layout's header slot in its own <header>, whose
+   box is exactly as tall as the header block inside it — so `position: sticky`
+   on that block would have no distance to travel and silently do nothing. The
+   SiteHeader widget therefore marks itself and the *wrapper* takes the sticky
+   positioning. Scoped by the attribute so a header built from plain blocks, or
+   one with "stick to the top" switched off, still scrolls away normally. */
+/* Descendant, not child: Puck's <Render> wraps every block in its own div, so
+   the widget is a grandchild of the slot wrapper, never a direct child. */
+header:has([data-pb-site-header="sticky"]) {
+	position: sticky;
+	top: 0;
+	z-index: 50;
+}

pagebuilder/translation/apply.ts

@@ -0,0 +1,54 @@
+import type { FieldPath } from './extract';
+
+// Objects and arrays are both indexable by a path segment — `obj["key"]` and
+// `arr[2]` alike — and arrays are `typeof === "object"`, so one guard covers
+// both.
+function isIndexable(value: unknown): value is Record<PropertyKey, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Write `translations[n]` back to the location `paths[n]` recorded, and
+ * re-serialize.
+ *
+ * The exact inverse of `extractTranslatableStrings`: feeding it the strings
+ * that function just extracted reproduces the input structurally. Props not
+ * named in `paths` are never touched, so a translation pass can't quietly
+ * rewrite a URL or drop a field it didn't understand.
+ */
+export function applyTranslatedStrings(
+  puckJson: string,
+  paths: FieldPath[],
+  translations: string[],
+): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(puckJson);
+  } catch {
+    // `extractTranslatableStrings` returns an empty result for unparseable
+    // input rather than throwing. These two are documented as exact inverses,
+    // so a caller that survived the first half must not be crashed by the
+    // second — hand the input straight back untouched.
+    return puckJson;
+  }
+
+  paths.forEach((path, index) => {
+    const translation = translations[index];
+    // Loose equality catches `undefined` (array shorter than `paths`) and a
+    // literal JSON `null` alike. Either way the original stands — writing
+    // `null` over real copy is the one outcome worse than not translating.
+    if (translation == null || path.length === 0) return;
+
+    // Walk to the container that directly holds the final segment.
+    let current: unknown = parsed;
+    for (let i = 0; i < path.length - 1; i++) {
+      if (!isIndexable(current)) return;
+      current = current[path[i]];
+    }
+    if (!isIndexable(current)) return;
+
+    current[path[path.length - 1]] = translation;
+  });
+
+  return JSON.stringify(parsed);
+}

pagebuilder/translation/extract.ts

@@ -0,0 +1,141 @@
+import type { ArrayField, Config, Field } from '@puckeditor/core';
+
+import { isTranslatableField } from './translatable-fields';
+
+/** One step of a {@link FieldPath}: an object key or an array index. */
+export type PathSegment = string | number;
+
+/**
+ * Locates one translatable string inside a parsed Puck document, as the list
+ * of segments walked from the root. Examples:
+ * - `["content", 2, "props", "text"]`
+ * - `["content", 0, "props", "items", 1, "links", 0, "label"]`
+ * - `["root", "props", "title"]`
+ *
+ * Depth-agnostic, so an array nested inside an array item is addressable.
+ * `applyTranslatedStrings` is the exact inverse.
+ */
+export type FieldPath = PathSegment[];
+
+export interface ExtractResult {
+  strings: string[];
+  paths: FieldPath[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Pull every human-readable string out of a serialized Puck document.
+ *
+ * Walks `content[]`, each `zones[*][]`, and `root.props`, resolving each
+ * block's field shape from `config` so non-copy props — URLs, colours, ids,
+ * enums, image pickers — are left alone. Recurses into array fields to any
+ * depth. Pure: no network, no React, no DOM.
+ *
+ * Both halves take and return the serialized JSON rather than parsed data,
+ * so a caller can hand a translated document straight back to storage without
+ * a re-serialize that might reorder keys.
+ */
+export function extractTranslatableStrings(puckJson: string, config: Config): ExtractResult {
+  const strings: string[] = [];
+  const paths: FieldPath[] = [];
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(puckJson);
+  } catch {
+    return { strings, paths };
+  }
+  if (!isRecord(parsed)) return { strings, paths };
+
+  function visitFields(
+    container: Record<string, unknown>,
+    fields: Record<string, Field>,
+    basePath: FieldPath,
+  ): void {
+    for (const [key, field] of Object.entries(fields)) {
+      const value = container[key];
+
+      // A slot holds whole *blocks*, not field-shaped items, so it recurses
+      // through `visitBlock` (which resolves each child's own field shape)
+      // rather than through `visitFields`. Without this, everything an author
+      // nested inside a Columns or Container would be invisible to the
+      // translator — the blocks are there, but nothing walks into them.
+      if (field?.type === 'slot') {
+        if (!Array.isArray(value)) continue;
+        value.forEach((child: unknown, index: number) =>
+          visitBlock(child, [...basePath, key, index]),
+        );
+        continue;
+      }
+
+      if (field?.type === 'array') {
+        if (!Array.isArray(value)) continue;
+        const arrayFields = (field as ArrayField).arrayFields as
+          | Record<string, Field>
+          | undefined;
+        if (!arrayFields) continue;
+        value.forEach((item: unknown, index: number) => {
+          if (!isRecord(item)) return;
+          // An array item's own fields may themselves include a slot —
+          // `Columns.columns[].content` is exactly that shape.
+          visitFields(item, arrayFields, [...basePath, key, index]);
+        });
+        continue;
+      }
+
+      if (isTranslatableField(key, field) && typeof value === 'string' && value.trim() !== '') {
+        strings.push(value);
+        paths.push([...basePath, key]);
+      }
+    }
+  }
+
+  function visitBlock(block: unknown, blockPath: FieldPath): void {
+    if (!isRecord(block)) return;
+    const props = block.props;
+    if (!isRecord(props)) return;
+
+    const type = typeof block.type === 'string' ? block.type : undefined;
+    const fields = type ? config.components?.[type]?.fields : config.root?.fields;
+    if (!fields) return;
+
+    visitFields(props, fields as Record<string, Field>, [...blockPath, 'props']);
+  }
+
+  const content = parsed.content;
+  if (Array.isArray(content)) {
+    content.forEach((block: unknown, index: number) => visitBlock(block, ['content', index]));
+  }
+
+  // Pre-slots documents keep nested blocks here. `migrateContent` folds these
+  // into slot props on load, but extraction runs against whatever is stored,
+  // which may not have been through the editor since.
+  const zones = parsed.zones;
+  if (isRecord(zones)) {
+    for (const [zoneKey, zoneBlocks] of Object.entries(zones)) {
+      if (!Array.isArray(zoneBlocks)) continue;
+      zoneBlocks.forEach((block: unknown, index: number) =>
+        visitBlock(block, ['zones', zoneKey, index]),
+      );
+    }
+  }
+
+  const root = parsed.root;
+  if (isRecord(root)) {
+    if (isRecord(root.props)) {
+      visitBlock(root, ['root']);
+    } else if (config.root?.fields) {
+      // Oldest shape: root props sit directly on `root` with no `props` nest.
+      // `visitBlock` bails on those because it requires `props`, which would
+      // make a pre-0.20 page's title quietly untranslatable — and this file
+      // already goes out of its way to handle the other legacy shape (`zones`),
+      // so handling one and not the other would be arbitrary.
+      visitFields(root, config.root.fields as Record<string, Field>, ['root']);
+    }
+  }
+
+  return { strings, paths };
+}

pagebuilder/translation/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Content i18n: pull the human copy out of a stored page, and write
+ * translations back into the same shape.
+ *
+ * Pure functions with no storage of their own — same as upstream. Nothing in
+ * this module decides *where* a translated document lives; that is a schema
+ * question for whichever host wants the feature.
+ *
+ * Distinct from UI i18n (the editor's own English strings), which is tracked
+ * separately in CLAUDE.md.
+ */
+
+export { applyTranslatedStrings } from './apply';
+export {
+  type ExtractResult,
+  extractTranslatableStrings,
+  type FieldPath,
+  type PathSegment,
+} from './extract';
+export { isTranslatableField, TRANSLATABLE_TEXT_TYPES } from './translatable-fields';