@focus-reactive/payload-plugin-translator 0.6.1 → 0.7.0

package/dist/client/shared/utils/componentPath.js

@@ -1,4 +1,4 @@
-const PACKAGE_NAME = '@focus-reactive/payload-plugin-translator';
+const PACKAGE_NAME = "@focus-reactive/payload-plugin-translator";
 /**
  * Creates a full path to a client component for Payload's import map.
  * @param relativePath - Path relative to the client folder (e.g., 'widgets/translate-document/ui/TranslateDocument.server')

package/dist/client/widgets/bulk-translation-dashboard/index.d.ts

@@ -1 +1 @@
-export { BulkDocumentTranslationDashboard } from './ui/BulkTranslationDashboard.export';
+export { BulkDocumentTranslationDashboard } from "./ui/BulkTranslationDashboard.export";

package/dist/client/widgets/bulk-translation-dashboard/index.js

@@ -1,3 +1,3 @@
-export { BulkDocumentTranslationDashboard } from './ui/BulkTranslationDashboard.export';
+export { BulkDocumentTranslationDashboard } from "./ui/BulkTranslationDashboard.export";
 
 //# sourceMappingURL=index.js.map

package/dist/client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.export.d.ts

@@ -1,5 +1,5 @@
-import type { AccessGuard } from '../../../../types/AccessGuard';
-import type { RawPayloadComponentExport } from '../../../shared/types/PayloadComponentExport';
+import type { AccessGuard } from "../../../../types/AccessGuard";
+import type { RawPayloadComponentExport } from "../../../../types/PayloadComponentExport";
 export declare class BulkDocumentTranslationDashboard implements RawPayloadComponentExport {
     readonly access: AccessGuard;
     serverProps?: object | Record<string, any> | undefined;

package/dist/client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.export.js

@@ -1,11 +1,11 @@
-import { AnyAccessGuard } from '../../../../server/shared';
-import { clientComponentPath } from '../../../shared/utils/componentPath';
+import { AnyAccessGuard } from "../../../../server/shared";
+import { clientComponentPath } from "../../../shared/utils/componentPath";
 export class BulkDocumentTranslationDashboard {
     access;
     serverProps;
     constructor(access = new AnyAccessGuard()){
         this.access = access;
-        this.path = clientComponentPath('widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.server');
+        this.path = clientComponentPath("widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.server");
         this.serverProps = {
             access
         };

package/dist/client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.js

@@ -1,15 +1,15 @@
-'use client';
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { toast, useLocale, useSelection } from '@payloadcms/ui';
-import { SelectAllStatus } from '@payloadcms/ui/providers/Selection';
-import { useEffect, useMemo } from 'react';
-import { TranslationsApi } from '../../../entities/translation';
-import { CollectionTranslationForm, FORM_FIELDS } from '../../../features/collection-translation-form';
-import { CollectionTranslationFormModel } from '../../../features/collection-translation-form/index.client';
-import CollectionTranslationPopup from '../../../features/collection-translation-popup';
-import { CollectionTranslationProgress } from '../../../features/collection-translation-progress';
-import { handleFormError } from '../../../shared/lib/forms/handle-form-error';
-import { useCollectionDashboardUrlParams } from '../../../shared/lib/payload/hooks/useCollectionDashboardUrlParams';
+import { toast, useLocale, useSelection } from "@payloadcms/ui";
+import { SelectAllStatus } from "@payloadcms/ui/providers/Selection";
+import { useEffect, useMemo } from "react";
+import { TranslationsApi } from "../../../entities/translation";
+import { CollectionTranslationForm, FORM_FIELDS } from "../../../features/collection-translation-form";
+import { CollectionTranslationFormModel } from "../../../features/collection-translation-form/index.client";
+import CollectionTranslationPopup from "../../../features/collection-translation-popup";
+import { CollectionTranslationProgress } from "../../../features/collection-translation-progress";
+import { handleFormError } from "../../../shared/lib/forms/handle-form-error";
+import { useCollectionDashboardUrlParams } from "../../../shared/lib/payload/hooks/useCollectionDashboardUrlParams";
 export default function BulkTranslationDashboard({ hasDrafts }) {
     const locale = useLocale();
     const { collection } = useCollectionDashboardUrlParams();

package/dist/client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.server.d.ts

@@ -1,5 +1,5 @@
-import type { BeforeListTableServerProps } from 'payload';
-import type { AccessGuard } from '../../../../types/AccessGuard';
+import type { BeforeListTableServerProps } from "payload";
+import type { AccessGuard } from "../../../../types/AccessGuard";
 type BulkTranslationDashboardServerProps = BeforeListTableServerProps & {
     access: AccessGuard;
 };

package/dist/client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.server.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { headers as getHeaders } from 'next/headers';
-import { collectionHasDrafts } from '../../../../server/shared/guards';
-import BulkTranslationDashboard from './BulkTranslationDashboard';
+import { headers as getHeaders } from "next/headers";
+import { collectionHasDrafts } from "../../../../server/shared/guards";
+import BulkTranslationDashboard from "./BulkTranslationDashboard";
 const BulkTranslationDashboardServer = async (props)=>{
     const headers = await getHeaders();
     const hasAccess = await props.access.check({

package/dist/client/widgets/bulk-translation-dashboard/ui/index.d.ts

@@ -1 +1 @@
-export { default } from './BulkTranslationDashboard';
+export { default } from "./BulkTranslationDashboard";

package/dist/client/widgets/bulk-translation-dashboard/ui/index.js

@@ -1,3 +1,3 @@
-export { default } from './BulkTranslationDashboard';
+export { default } from "./BulkTranslationDashboard";
 
 //# sourceMappingURL=index.js.map

package/dist/client/widgets/translate-document/index.d.ts

@@ -1 +1 @@
-export { TranslateDocumentExport } from './ui/TranslateDocument.export';
+export { TranslateDocumentExport } from "./ui/TranslateDocument.export";

package/dist/client/widgets/translate-document/index.js

@@ -1,3 +1,3 @@
-export { TranslateDocumentExport } from './ui/TranslateDocument.export';
+export { TranslateDocumentExport } from "./ui/TranslateDocument.export";
 
 //# sourceMappingURL=index.js.map

package/dist/client/widgets/translate-document/ui/TranslateDocument.export.d.ts

@@ -1,6 +1,6 @@
-import type { CollectionConfig } from 'payload';
-import type { AccessGuard } from '../../../../types/AccessGuard';
-import type { RawPayloadComponentExport } from '../../../shared/types/PayloadComponentExport';
+import type { CollectionConfig } from "payload";
+import type { AccessGuard } from "../../../../types/AccessGuard";
+import type { RawPayloadComponentExport } from "../../../../types/PayloadComponentExport";
 export declare class TranslateDocumentExport implements RawPayloadComponentExport {
     readonly collection: CollectionConfig;
     readonly access: AccessGuard;

package/dist/client/widgets/translate-document/ui/TranslateDocument.export.js

@@ -1,5 +1,5 @@
-import { AnyAccessGuard } from '../../../../server/shared';
-import { clientComponentPath } from '../../../shared/utils/componentPath';
+import { AnyAccessGuard } from "../../../../server/shared";
+import { clientComponentPath } from "../../../shared/utils/componentPath";
 export class TranslateDocumentExport {
     collection;
     access;
@@ -7,7 +7,7 @@ export class TranslateDocumentExport {
     constructor(collection, access = new AnyAccessGuard()){
         this.collection = collection;
         this.access = access;
-        this.path = clientComponentPath('widgets/translate-document/ui/TranslateDocument.server');
+        this.path = clientComponentPath("widgets/translate-document/ui/TranslateDocument.server");
         this.serverProps = {
             collection,
             access

package/dist/client/widgets/translate-document/ui/TranslateDocument.js

@@ -1,16 +1,16 @@
-'use client';
+"use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { toast, useLocale } from '@payloadcms/ui';
-import { useEffect, useMemo } from 'react';
-import { CompletedTranslationStatus, TranslationsApi } from '../../../entities/translation';
-import { OpenDocumentTranslationPopup } from '../../../features/open-document-translation-popup';
-import { DocumentTranslationForm, FORM_FIELDS } from '../../../features/translate-document-form';
-import { DocumentTranslationFormModel } from '../../../features/translate-document-form/index.client';
-import { handleFormError } from '../../../shared/lib/forms/handle-form-error';
-import { useCollectionDocumentUrlParams } from '../../../shared/lib/payload/hooks/useCollectionDocumentUrlParams';
-import { DocumentTranslationProgressFailed } from '../../../features/document-translation-progress-failed';
-import { DocumentTranslationProgressRunning } from '../../../features/document-translation-progress-running';
-import { DocumentTranslationProgressPending } from '../../../features/document-translation-progress-pending';
+import { toast, useLocale } from "@payloadcms/ui";
+import { useEffect, useMemo } from "react";
+import { CompletedTranslationStatus, TranslationsApi } from "../../../entities/translation";
+import { OpenDocumentTranslationPopup } from "../../../features/open-document-translation-popup";
+import { DocumentTranslationForm, FORM_FIELDS } from "../../../features/translate-document-form";
+import { DocumentTranslationFormModel } from "../../../features/translate-document-form/index.client";
+import { handleFormError } from "../../../shared/lib/forms/handle-form-error";
+import { useCollectionDocumentUrlParams } from "../../../shared/lib/payload/hooks/useCollectionDocumentUrlParams";
+import { DocumentTranslationProgressFailed } from "../../../features/document-translation-progress-failed";
+import { DocumentTranslationProgressRunning } from "../../../features/document-translation-progress-running";
+import { DocumentTranslationProgressPending } from "../../../features/document-translation-progress-pending";
 const TranslateDocument = ({ hasDrafts })=>{
     const locale = useLocale();
     const params = useCollectionDocumentUrlParams();
@@ -65,18 +65,18 @@ const TranslateDocument = ({ hasDrafts })=>{
                         ]
                     })
             }),
-            data?.status === 'completed' && /*#__PURE__*/ _jsx(CompletedTranslationStatus, {
+            data?.status === "completed" && /*#__PURE__*/ _jsx(CompletedTranslationStatus, {
                 sourceLocale: data.input.source_lng,
                 targetLocale: data.input.target_lng,
                 completed_at: data.completed_at
             }),
-            data?.status === 'failed' && /*#__PURE__*/ _jsx(DocumentTranslationProgressFailed, {
+            data?.status === "failed" && /*#__PURE__*/ _jsx(DocumentTranslationProgressFailed, {
                 data: data
             }),
-            data?.status === 'running' && /*#__PURE__*/ _jsx(DocumentTranslationProgressRunning, {
+            data?.status === "running" && /*#__PURE__*/ _jsx(DocumentTranslationProgressRunning, {
                 data: data
             }),
-            data?.status === 'pending' && /*#__PURE__*/ _jsx(DocumentTranslationProgressPending, {
+            data?.status === "pending" && /*#__PURE__*/ _jsx(DocumentTranslationProgressPending, {
                 data: data
             })
         ]

package/dist/client/widgets/translate-document/ui/TranslateDocument.server.d.ts

@@ -1,5 +1,5 @@
-import type { BeforeDocumentControlsServerProps, CollectionConfig } from 'payload';
-import type { AccessGuard } from '../../../../types/AccessGuard';
+import type { BeforeDocumentControlsServerProps, CollectionConfig } from "payload";
+import type { AccessGuard } from "../../../../types/AccessGuard";
 type TranslateDocumentServerProps = BeforeDocumentControlsServerProps & {
     collection: CollectionConfig;
     access: AccessGuard;

package/dist/client/widgets/translate-document/ui/TranslateDocument.server.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { headers as getHeaders } from 'next/headers';
-import { collectionHasDrafts } from '../../../../server/shared/guards';
-import TranslateDocument from './TranslateDocument';
+import { headers as getHeaders } from "next/headers";
+import { collectionHasDrafts } from "../../../../server/shared/guards";
+import TranslateDocument from "./TranslateDocument";
 async function TranslateDocumentServer(props) {
     const headers = await getHeaders();
     const hasAccess = await props.access.check({

package/dist/client/widgets/translate-document/ui/index.d.ts

@@ -1 +1 @@
-export { default } from './TranslateDocument';
+export { default } from "./TranslateDocument";

package/dist/client/widgets/translate-document/ui/index.js

@@ -1,3 +1,3 @@
-export { default } from './TranslateDocument';
+export { default } from "./TranslateDocument";
 
 //# sourceMappingURL=index.js.map

package/dist/client/widgets/translate-field-control/ui/TranslateFieldControl.export.d.ts

@@ -1,4 +1,4 @@
-import type { RawPayloadComponentExport } from "../../../shared/types/PayloadComponentExport";
+import type { RawPayloadComponentExport } from "../../../../types/PayloadComponentExport";
 /**
  * Import-map reference to the per-field Translate control. Appended to a field's
  * `admin.components.beforeInput` by `withFieldTranslation(field)`, so it renders just above the

package/dist/client/widgets/translate-field-control/ui/styles.module.scss

@@ -45,4 +45,4 @@
   display: inline-flex;
   width: fit-content;
   margin-bottom: 0.25rem;
-}
+}

package/dist/{server/modules/translation-levels → composition/levels}/collectionLevel.d.ts

@@ -1,4 +1,4 @@
-import type { TranslationLevel } from "./types";
+import type { TranslationLevel } from "../../server/modules/translation-levels";
 /**
  * Bulk collection translation: a dashboard on the list view (translate many
  * documents at once), backed by the same shared document-translation API as

package/dist/{server/modules/translation-levels → composition/levels}/collectionLevel.js

@@ -1,4 +1,4 @@
-import { BulkDocumentTranslationDashboard } from "../../../client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.export";
+import { BulkDocumentTranslationDashboard } from "../../client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.export";
 import { useDocTranslationApi } from "./useDocTranslationApi";
 /**
  * Bulk collection translation: a dashboard on the list view (translate many

package/dist/{server/modules/translation-levels → composition/levels}/documentLevel.d.ts

@@ -1,4 +1,4 @@
-import type { TranslationLevel } from "./types";
+import type { TranslationLevel } from "../../server/modules/translation-levels";
 /**
  * Per-document translation: a popup control on the document edit view, backed by
  * the shared document-translation API (async/job by default; synchronous if the

package/dist/{server/modules/translation-levels → composition/levels}/documentLevel.js

@@ -1,4 +1,4 @@
-import { TranslateDocumentExport } from "../../../client/widgets/translate-document";
+import { TranslateDocumentExport } from "../../client/widgets/translate-document";
 import { useDocTranslationApi } from "./useDocTranslationApi";
 /**
  * Per-document translation: a popup control on the document edit view, backed by

package/dist/{server/modules/translation-levels → composition/levels}/fieldLevel.d.ts

@@ -1,4 +1,4 @@
-import type { TranslationLevel } from "./types";
+import type { TranslationLevel } from "../../server/modules/translation-levels";
 /**
  * Field-level translation surface: a synchronous `POST {basePath}/field` endpoint that translates
  * a single declared field **from a chosen source locale** — it reads the field's value from the

package/dist/{server/modules/translation-levels → composition/levels}/fieldLevel.js

@@ -1,4 +1,4 @@
-import { createFieldRoute } from "../../features/translate-field";
+import { createFieldRoute } from "../../server/features/translate-field";
 /**
  * Field-level translation surface: a synchronous `POST {basePath}/field` endpoint that translates
  * a single declared field **from a chosen source locale** — it reads the field's value from the

package/dist/composition/levels/index.d.ts

@@ -0,0 +1,3 @@
+export { documentLevel } from "./documentLevel";
+export { collectionLevel } from "./collectionLevel";
+export { fieldLevel } from "./fieldLevel";

package/dist/composition/levels/index.js

@@ -0,0 +1,5 @@
+export { documentLevel } from "./documentLevel";
+export { collectionLevel } from "./collectionLevel";
+export { fieldLevel } from "./fieldLevel";
+
+//# sourceMappingURL=index.js.map

package/dist/{server/modules/translation-levels → composition/levels}/useDocTranslationApi.d.ts

@@ -1,4 +1,4 @@
-import type { LevelContext } from "./types";
+import type { LevelContext } from "../../server/modules/translation-levels";
 /**
  * Contribute the runner-agnostic document-translation API — the shared 6-route
  * bundle, bound to the level context's runner. Both `documentLevel` and

package/dist/{server/modules/translation-levels → composition/levels}/useDocTranslationApi.js

@@ -1,4 +1,4 @@
-import { createTranslationRoutes } from "../../features/createTranslationRoutes";
+import { createTranslationRoutes } from "../../server/features/createTranslationRoutes";
 /**
  * Contribute the runner-agnostic document-translation API — the shared 6-route
  * bundle, bound to the level context's runner. Both `documentLevel` and

package/dist/core/content-projection/computeSourceFingerprint.d.ts

@@ -0,0 +1,15 @@
+import type { FieldLike } from "../field-traversal";
+/**
+ * The staleness baseline: a stable hash of a document's translatable content.
+ * `CURRENT = computeSourceFingerprint(sourceDoc, schema)` — the value provenance stores at translation
+ * time and #50 recomputes to detect source drift. A named composition of
+ * {@link projectTranslatableContent} + {@link fingerprint} so the "how to fingerprint source content"
+ * contract lives in one place (callers don't re-wire the two primitives). Reorder-invariant and
+ * text-nodes-only, inheriting those properties from its parts.
+ *
+ * @param doc - The source document to fingerprint (never mutated).
+ * @param schema - The ORIGINAL (un-sanitized) field schema.
+ * @returns A hex sha256 digest of the projected translatable content.
+ * @since 0.7.0
+ */
+export declare function computeSourceFingerprint(doc: Record<string, unknown>, schema: FieldLike[]): string;

package/dist/core/content-projection/computeSourceFingerprint.js

@@ -0,0 +1,19 @@
+import { projectTranslatableContent } from "./contentProjector";
+import { fingerprint } from "./fingerprinter";
+/**
+ * The staleness baseline: a stable hash of a document's translatable content.
+ * `CURRENT = computeSourceFingerprint(sourceDoc, schema)` — the value provenance stores at translation
+ * time and #50 recomputes to detect source drift. A named composition of
+ * {@link projectTranslatableContent} + {@link fingerprint} so the "how to fingerprint source content"
+ * contract lives in one place (callers don't re-wire the two primitives). Reorder-invariant and
+ * text-nodes-only, inheriting those properties from its parts.
+ *
+ * @param doc - The source document to fingerprint (never mutated).
+ * @param schema - The ORIGINAL (un-sanitized) field schema.
+ * @returns A hex sha256 digest of the projected translatable content.
+ * @since 0.7.0
+ */ export function computeSourceFingerprint(doc, schema) {
+    return fingerprint(projectTranslatableContent(doc, schema));
+}
+
+//# sourceMappingURL=computeSourceFingerprint.js.map

package/dist/core/content-projection/contentProjector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `projectTranslatableContent` — the pure, read-only `ContentProjector` (slice 6 design,
+ * `docs/plans/2026-06-30-slice6-contentprojector-idpath-design.md`).
+ *
+ * Produces one `{ idPath, text }` entry per translatable leaf of a document — the projection the
+ * provenance fingerprint (#47) hashes. It reuses the SAME traversal engine ({@link walkFields}),
+ * the SAME leaf-selection predicate + text notion ({@link isTranslatableLeaf} /
+ * {@link leafSourceText}) as the translation pipeline's `FieldChunkCollector`, so projection and
+ * translation can never disagree on which content is translatable. Payload-free and read-only:
+ * it never mutates the document and never captures write handles.
+ */
+import type { FieldLike } from "../field-traversal/types";
+import type { IdPath } from "./idPath";
+/** One translatable leaf of a document: WHERE it lives ({@link IdPath}) and WHAT text it holds. */
+export interface ProjectionEntry {
+    idPath: IdPath;
+    text: string;
+}
+/**
+ * Project a document's translatable content into a flat, location-keyed list.
+ *
+ * @param doc - The source document to read (never mutated).
+ * @param schema - The ORIGINAL (un-sanitized) field schema — preserves nested `localized` flags.
+ * @returns One entry per translatable, localized, non-excluded leaf that holds text, in traversal
+ * order. `richText` is field-level (one entry, joined node text). Reordering array/blocks elements
+ * does not change the set (each entry's `idPath` is keyed by element `id`, not index).
+ */
+export declare function projectTranslatableContent(doc: Record<string, unknown>, schema: FieldLike[]): ProjectionEntry[];

package/dist/core/content-projection/contentProjector.js

@@ -0,0 +1,97 @@
+/**
+ * `projectTranslatableContent` — the pure, read-only `ContentProjector` (slice 6 design,
+ * `docs/plans/2026-06-30-slice6-contentprojector-idpath-design.md`).
+ *
+ * Produces one `{ idPath, text }` entry per translatable leaf of a document — the projection the
+ * provenance fingerprint (#47) hashes. It reuses the SAME traversal engine ({@link walkFields}),
+ * the SAME leaf-selection predicate + text notion ({@link isTranslatableLeaf} /
+ * {@link leafSourceText}) as the translation pipeline's `FieldChunkCollector`, so projection and
+ * translation can never disagree on which content is translatable. Payload-free and read-only:
+ * it never mutates the document and never captures write handles.
+ */ import { resolveBlockFields, walkFields } from "../field-traversal";
+import { isObject } from "../utils/isObject";
+import { elementSegment, makeIdPath } from "./idPath";
+import { isTranslatableLeaf, leafSourceText } from "./translatableLeaf";
+/**
+ * Project a document's translatable content into a flat, location-keyed list.
+ *
+ * @param doc - The source document to read (never mutated).
+ * @param schema - The ORIGINAL (un-sanitized) field schema — preserves nested `localized` flags.
+ * @returns One entry per translatable, localized, non-excluded leaf that holds text, in traversal
+ * order. `richText` is field-level (one entry, joined node text). Reordering array/blocks elements
+ * does not change the set (each entry's `idPath` is keyed by element `id`, not index).
+ */ export function projectTranslatableContent(doc, schema) {
+    const entries = [];
+    const walker = {
+        enterObject (field, cursor) {
+            const value = cursor.data[field.name];
+            if (!isObject(value)) return "skip";
+            return {
+                data: value,
+                segments: [
+                    ...cursor.segments,
+                    {
+                        kind: "key",
+                        name: field.name
+                    }
+                ]
+            };
+        },
+        enterList (field, cursor) {
+            const value = cursor.data[field.name];
+            if (!Array.isArray(value)) return "skip";
+            const isBlocks = field.type === "blocks";
+            const listSegments = [
+                ...cursor.segments,
+                {
+                    kind: "key",
+                    name: field.name
+                }
+            ];
+            const children = [];
+            value.forEach((item, index)=>{
+                if (!isObject(item)) return;
+                const fields = isBlocks ? resolveBlockFields(field, item) : field.fields;
+                if (!fields) return; // unknown blockType → skip element
+                children.push({
+                    cursor: {
+                        data: item,
+                        segments: [
+                            ...listSegments,
+                            elementSegment(item, isBlocks, index)
+                        ]
+                    },
+                    fields,
+                    key: index
+                });
+            });
+            return children;
+        },
+        leaf (field, cursor) {
+            if (!isTranslatableLeaf(field)) return undefined;
+            const text = leafSourceText(field, cursor.data[field.name]);
+            if (text === null) return undefined;
+            entries.push({
+                idPath: makeIdPath([
+                    ...cursor.segments,
+                    {
+                        kind: "key",
+                        name: field.name
+                    }
+                ]),
+                text
+            });
+            return undefined;
+        },
+        combine () {
+            return undefined; // collect-only — nothing to assemble
+        }
+    };
+    walkFields(schema, {
+        data: doc,
+        segments: []
+    }, walker);
+    return entries;
+}
+
+//# sourceMappingURL=contentProjector.js.map

package/dist/core/content-projection/fingerprinter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `fingerprint` — a stable, reorder-invariant hash of a content projection (slice 6 design,
+ * `docs/plans/2026-06-30-slice6-contentprojector-idpath-design.md`). It is the roll-up the
+ * provenance staleness check compares over time: `CURRENT = fingerprint(projectTranslatableContent(
+ * sourceDoc, schema))`.
+ *
+ * Entries are sorted by `idPath` before hashing, so reordering array/blocks elements (which keeps
+ * the same `{ idPath, text }` set) does not move the hash — only a real content change does. The
+ * key and the value are length-prefixed so no shift of the text/key boundary can alias two
+ * different projections onto the same serialization.
+ *
+ * Depends only on `node:crypto` (a node built-in) — payload-free, so it can move to
+ * `@repo/translator-core` unchanged.
+ */
+import type { IdPath } from "./idPath";
+interface ProjectionEntry {
+    idPath: IdPath;
+    text: string;
+}
+/**
+ * Hash a projection into a hex sha256 digest. Order-independent (sorted by `idPath` first) and
+ * deterministic.
+ *
+ * @param projection - The `{ idPath, text }` entries from {@link projectTranslatableContent}.
+ * @returns A hex sha256 string; equal projections (same entries, any order) hash equally.
+ */
+export declare function fingerprint(projection: ProjectionEntry[]): string;
+export {};

package/dist/core/content-projection/fingerprinter.js

@@ -0,0 +1,29 @@
+/**
+ * `fingerprint` — a stable, reorder-invariant hash of a content projection (slice 6 design,
+ * `docs/plans/2026-06-30-slice6-contentprojector-idpath-design.md`). It is the roll-up the
+ * provenance staleness check compares over time: `CURRENT = fingerprint(projectTranslatableContent(
+ * sourceDoc, schema))`.
+ *
+ * Entries are sorted by `idPath` before hashing, so reordering array/blocks elements (which keeps
+ * the same `{ idPath, text }` set) does not move the hash — only a real content change does. The
+ * key and the value are length-prefixed so no shift of the text/key boundary can alias two
+ * different projections onto the same serialization.
+ *
+ * Depends only on `node:crypto` (a node built-in) — payload-free, so it can move to
+ * `@repo/translator-core` unchanged.
+ */ import { createHash } from "node:crypto";
+const serializeEntry = (entry)=>`${entry.idPath.length}:${entry.idPath}=${entry.text.length}:${entry.text}`;
+/**
+ * Hash a projection into a hex sha256 digest. Order-independent (sorted by `idPath` first) and
+ * deterministic.
+ *
+ * @param projection - The `{ idPath, text }` entries from {@link projectTranslatableContent}.
+ * @returns A hex sha256 string; equal projections (same entries, any order) hash equally.
+ */ export function fingerprint(projection) {
+    const serialized = [
+        ...projection
+    ].sort((a, b)=>a.idPath < b.idPath ? -1 : a.idPath > b.idPath ? 1 : 0).map(serializeEntry).join("\n");
+    return createHash("sha256").update(serialized).digest("hex");
+}
+
+//# sourceMappingURL=fingerprinter.js.map

package/dist/core/content-projection/idPath.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `IdPath` — the stable, location-based identity of a translatable leaf (slice 6 design,
+ * `docs/plans/2026-06-30-slice6-contentprojector-idpath-design.md`).
+ *
+ * It is the field path from the document root, with one crucial change over a positional path:
+ * **array/blocks element indices are replaced by the element's `id`** (`+ blockType` for blocks),
+ * so the path survives reordering and means the same thing across time. Group/tab/leaf name
+ * segments are unchanged; an element with no `id` falls back to a marked positional segment.
+ *
+ * `idPath` is *where* a piece lives (identity), never *what* it contains — so it can be compared
+ * across time to detect content drift. The whole grammar (escaping, blockType folding, fallback)
+ * lives in {@link makeIdPath}, the sole constructor, so it can never drift.
+ */
+export type IdPath = string & {
+    readonly __brand: "IdPath";
+};
+/**
+ * One structural step of an {@link IdPath}. Callers push these while walking; only
+ * {@link makeIdPath} renders them to a string, keeping the grammar in one place.
+ */
+export type PathSegment = {
+    kind: "key";
+    name: string;
+} | {
+    kind: "element";
+    id: string;
+    blockType?: string;
+} | {
+    kind: "index";
+    index: number;
+};
+/**
+ * The sole constructor of an {@link IdPath}. Renders structural segments to the branded string.
+ */
+export declare function makeIdPath(segments: PathSegment[]): IdPath;
+/**
+ * Build the {@link PathSegment} for one array/blocks element from its data item: keyed by the
+ * element's `id` (with `blockType` folded in for blocks), or a positional fallback when the element
+ * carries no usable `id`.
+ *
+ * @param item - The element's data object.
+ * @param isBlocks - Whether the parent field is a `blocks` field (then `blockType` is folded in).
+ * @param index - Position, used only for the no-id fallback.
+ */
+export declare function elementSegment(item: {
+    id?: unknown;
+    blockType?: unknown;
+}, isBlocks: boolean, index: number): PathSegment;