@milaboratories/pl-middle-layer 1.71.16 → 1.73.0

package/src/middle_layer/sharing_list.ts

@@ -1,26 +1,26 @@
-import type { PruningFunction } from "@milaboratories/pl-tree";
+import type { PlTreeNodeAccessor, PruningFunction } from "@milaboratories/pl-tree";
 import { SynchronizedTreeState } from "@milaboratories/pl-tree";
 import type { Filter, PlClient, SignedResourceId } from "@milaboratories/pl-client";
 import {
   isEveryoneUserLogin,
-  resourceIdToString,
   resourceType,
   resourceTypesEqual,
   treeFilter,
 } from "@milaboratories/pl-client";
 import { Computable } from "@milaboratories/computable";
 import type { MiddleLayerEnvironment } from "./middle_layer";
-import type { ProjectId } from "@milaboratories/pl-model-common";
+import type { ProjectId, TemplateId } from "@milaboratories/pl-model-common";
+import type { FolderId } from "@milaboratories/pl-model-middle-layer";
 import type {
-  EnvelopeAcceptance,
   EnvelopeData,
   EnvelopeMode,
   EnvelopePayloadKind,
   ShareId,
 } from "../model/sharing_model";
 import {
-  AcceptanceFieldPrefix,
-  asShareId,
+  hiddenFieldShareId,
+  isHiddenField,
+  envelopeFolderRoot,
   envelopeProjectMap,
   normalizeEnvelopeData,
   SharedEnvelopeResourceType,
@@ -28,84 +28,78 @@ import {
   SharingStateResourceType,
 } from "../model/sharing_model";
 
+/** What a folder share carries, as both share lists show it. */
+export interface EnvelopeFolderSummary {
+  label: string;
+  /** Donor's own id of the shared folder. */
+  source: FolderId;
+  folderCount: number;
+  projectCount: number;
+  templateCount: number;
+}
+
 /** Donor-facing view of one outgoing share. */
 export interface OutgoingShare {
-  shareId: ShareId; // stable logical identity of the share, preserved across changes
+  shareId: ShareId; // identity of the share; a share that replaces it gets its own
   sharedAt: number; // this instance's creation time (ms epoch)
   expiresAt?: number; // EnvelopeData.expiresAt; null maps to undefined = never expires
   mode: EnvelopeMode;
   title: string; // display name shown to recipients; defaults to the first project's name
-  /** What the share carries — a pack of projects, or one template document. */
+  /** What the share carries — a pack of projects, one template document, or a folder subtree. */
   payloadKind: EnvelopePayloadKind;
-  /** One entry per project in the pack, so the change UI can offer a per-project decision.
-   *  `projectId` is the donor's source project id; `updatedAt` is when this project's
-   *  snapshot was last (re)taken. Empty for a template share. */
+  /** One entry per project in the pack. `projectId` is the donor's source project id, which is
+   *  what the share dialog matches a project's prior shares on; `updatedAt` is when this
+   *  project's snapshot was taken. Empty for any share that is not a pack of projects. */
   projects: { projectId: ProjectId; label: string; updatedAt: number }[];
-  /** The shared template, for a template share; absent for a project share. */
-  template?: { label: string; blockCount: number };
+  /** The shared template, for a template share; absent otherwise. `source` is the donor's own
+   *  template id, which is what the share dialog matches a template's prior shares on; a share
+   *  made before it was carried has none and matches nothing. */
+  template?: { label: string; blockCount: number; source?: TemplateId };
+  /** The shared folder, for a folder share; absent otherwise. `label` is the root folder's own
+   *  name, `source` the donor's own id for it — what a prior share of the same folder is matched
+   *  on — and the counts are of the whole subtree, the root folder itself excluded. */
+  folder?: EnvelopeFolderSummary;
+  /** What the shared thing says about itself: a template's, a folder's, or the one project's of
+   *  a single-project share. Absent for a pack of several, which has no one thing to describe. */
+  description?: string;
   /** Full recipient logins, from `ListGrants` on the envelope; `["*"]` for everyone-shares. */
   recipients: string[];
-  /** Whether {@link responses} can ever be populated for this share. A template share is granted
-   *  read-only, so no recipient can record a reply on the envelope and the donor never learns who
-   *  accepted — a view must say so rather than render an empty response list as "nobody yet". */
-  responsesAvailable: boolean;
-  /** Per recipient who has responded: their decision and when, from acceptance/{login}. */
-  responses: Record<string, { action: "accepted" | "rejected"; timestamp: number }>;
-}
-
-/** Per-project view for the donor's change UI, from the envelope's `projects` payload; empty
- *  for a payload that carries no project. */
-function envelopeProjects(data: EnvelopeData): OutgoingShare["projects"] {
-  return Object.values(envelopeProjectMap(data)).map((p) => ({
-    projectId: p.source,
-    label: p.label,
-    updatedAt: p.updatedAt,
-  }));
 }
 
-/** Acceptor-facing view of one pending share. */
-export interface PendingShare {
+/**
+ * Recipient-facing view of one share that is open to this user.
+ *
+ * A share is a shelf, not an invitation: it stays listed for as long as the envelope lives, and
+ * the recipient may copy from it any number of times. {@link hidden} is that recipient's own
+ * private choice to stop seeing it, and it can be undone.
+ */
+export interface AvailableShare {
   shareId: ShareId;
   sender: string; // EnvelopeData.sender, display only
   title: string; // display name shown to recipients; defaults to the first project's name
-  mode: EnvelopeMode; // v1 renders only "copy" entries
-  /** What the offer carries, so the recipient is told what they are being offered — projects to
-   *  copy, or a template for their own shelf. */
+  mode: EnvelopeMode;
+  /** What the share carries — projects to copy, a template to add to the recipient's templates,
+   *  or a folder subtree to rebuild in the recipient's tree. */
   payloadKind: EnvelopePayloadKind;
   grantedAt: number;
+  /** What the shared thing says about itself. See {@link OutgoingShare.description}. */
+  description?: string;
+  /** The shared folder, for a folder share; absent otherwise. See {@link OutgoingShare.folder}. */
+  folder?: EnvelopeFolderSummary;
+  /** Whether this recipient has put it out of sight. Hidden shares are listed, not dropped: the
+   *  view that shows them is what "show hidden" turns on. */
+  hidden: boolean;
 }
 
-const SharingOutboxPruningFunction: PruningFunction = (resource) => {
-  if (
-    !resourceTypesEqual(resource.type, SharingOutboxResourceType) &&
-    !resourceTypesEqual(resource.type, SharedEnvelopeResourceType)
-  )
-    return [];
-  return resource.fields;
-};
-
-// Server-side traversal scope (modern resourceTree path). Pruning is client-side ONLY and does
-// NOT stop the backend walk — without a fieldFilter the backend descends through the envelope's
-// project/{uuid} snapshots into the whole project graph (StreamManager etc.), whose field-driven
-// finality predicate then throws on the pruned-to-[] fields. Following fields only FROM the outbox
-// and the envelope stops the walk at the project snapshots (UserProject), which we never traverse.
-const SharingOutboxFieldFilter: Filter = treeFilter.or(
-  treeFilter.resourceTypeEq(SharingOutboxResourceType.name),
-  treeFilter.resourceTypeEq(SharedEnvelopeResourceType.name),
-);
-
-/** Intermediate of an outgoing share before its full recipient list is fetched: everything the
- *  tree carries synchronously, plus the envelope's signed id for the async `ListGrants` enrich. */
-type OutgoingShareDraft = Omit<OutgoingShare, "recipients"> & { envelopeRid: SignedResourceId };
+/** A live envelope discovered in the recipient's shared-resource tree: its signed resource id and
+ *  decoded {@link EnvelopeData}. A copy out of a share finds it by `data.shareId`. */
+export type LiveEnvelope = { rid: SignedResourceId; data: EnvelopeData };
 
 /**
  * Reactive view of the donor's own outbox. Reads each live envelope's immutable
- * {@link EnvelopeData} plus the per-recipient `acceptance/{login}` records from the tree, then
- * enriches each share's full recipient list via `ListGrants` on the envelope (`["*"]` for an
- * everyone-share). `ListGrants` is gated backend-side to the envelope owner (the donor), which is
- * exactly who reads this view.
- *
- * API-level only in M1 (no UI).
+ * {@link EnvelopeData} from the tree, then enriches each share's full recipient list via
+ * `ListGrants` on the envelope (`["*"]` for an everyone-share). `ListGrants` is gated backend-side
+ * to the envelope owner (the donor), which is exactly who reads this view.
  */
 export function createOutgoingSharesComputable(
   pl: PlClient,
@@ -126,16 +120,8 @@ export function createOutgoingSharesComputable(
         const data = normalizeEnvelopeData(envelope.getDataAsJson<unknown>());
         if (data === undefined) continue; // unknown version or payload kind — not ours to show
 
-        const responses: OutgoingShare["responses"] = {};
-        for (const f of envelope.listDynamicFields()) {
-          if (!f.startsWith(AcceptanceFieldPrefix)) continue;
-          const login = f.slice(AcceptanceFieldPrefix.length);
-          const acc = envelope.traverse(f);
-          const accData = acc?.getDataAsJson<EnvelopeAcceptance>();
-          if (accData === undefined) continue;
-          responses[login] = { action: accData.action, timestamp: accData.timestamp };
-        }
-
+        const folder = envelopeFolderSummary(data);
+        const description = envelopeDescription(data);
         drafts.push({
           shareId: data.shareId,
           sharedAt: data.sharedAt,
@@ -149,11 +135,12 @@ export function createOutgoingSharesComputable(
                 template: {
                   label: data.payload.label,
                   blockCount: data.payload.document.blocks.length,
+                  ...(data.payload.source === undefined ? {} : { source: data.payload.source }),
                 },
               }
             : {}),
-          responsesAvailable: data.payload.kind !== "template",
-          responses,
+          ...(folder === undefined ? {} : { folder }),
+          ...(description === undefined ? {} : { description }),
           envelopeRid: envelope.id,
         });
       }
@@ -215,26 +202,12 @@ export async function createOutgoingShares(
   return { computable: createOutgoingSharesComputable(pl, tree), tree };
 }
 
-const DecisionFieldPrefix = "decision/";
-
-const SharedEnvelopePruningFunction: PruningFunction = (resource) => {
-  if (!resourceTypesEqual(resource.type, SharedEnvelopeResourceType)) return [];
-  return resource.fields;
-};
-
-// Discovery only needs each envelope's immutable EnvelopeData (basic resource data); it must NOT
-// descend into the project snapshots. Following fields only FROM the envelope stops the walk at
-// the UserProject snapshots (their fields are never followed).
-const PendingSharesFieldFilter: Filter = treeFilter.resourceTypeEq(SharedEnvelopeResourceType.name);
-
 /**
- * Creates the acceptor's shared-resource discovery tree (a `{kind:'shared'}` seed over
- * {@link SharedEnvelopeResourceType}) plus the {@link PendingShare} computable over it.
- *
- * An envelope surfaces only when its shareId has NO decision/{shareId} on SharingState —
- * the dedup is applied by the caller, which holds the SharingState tree.
+ * Creates the recipient's shared-resource discovery tree: a `{kind:'shared'}` seed over
+ * {@link SharedEnvelopeResourceType}. {@link createAvailableSharesComputable} and
+ * {@link createLiveEnvelopesComputable} both read it.
  */
-export async function createPendingSharesTree(
+export async function createAvailableSharesTree(
   pl: PlClient,
   env: MiddleLayerEnvironment,
 ): Promise<SynchronizedTreeState> {
@@ -250,83 +223,58 @@ export async function createPendingSharesTree(
     {
       ...env.ops.defaultTreeOptions,
       pruning: SharedEnvelopePruningFunction,
-      fieldFilter: PendingSharesFieldFilter,
+      fieldFilter: AvailableSharesFieldFilter,
     },
     env.logger,
   );
 }
 
-/** A live envelope discovered in the acceptor's shared-resource tree: its signed resource id and
- *  decoded {@link EnvelopeData}. The accept/reject flow keys these by `data.shareId`. */
-export type LiveEnvelope = { rid: SignedResourceId; data: EnvelopeData };
-
 /**
- * Builds a Computable yielding the acceptor's currently-live envelopes, read from the
+ * Builds a Computable yielding the recipient's currently-live envelopes, read from the
  * shared-resource discovery tree the ML already maintains — the single discovery mechanism.
- * Accept/reject `.getValue()` this instead of re-streaming `ListUserResources`, so there is no
- * second discovery path. The envelope's signed `rid` (from the tree node) is what the write tx
- * needs; `copyEnvelopeProjectsIntoList` reads the project snapshots itself inside the tx.
+ * A copy out of a share `.getValue()`s this instead of re-streaming `ListUserResources`, so there
+ * is no second discovery path. The envelope's signed `rid` (from the tree node) is what the write
+ * tx needs; `copyEnvelopeProjectsIntoList` reads the project snapshots itself inside the tx.
  *
- * Returns `undefined` while the tree is still empty/unresolved (mirrors the other tree-backed
- * computables here). Yields a flat list; the caller dedups by `shareId` — at most one live
- * envelope per shareId is expected (the donor keeps one), and a replace tears the old one down.
+ * Yields a flat list; the caller dedups by `shareId` — at most one live envelope per shareId is
+ * expected (the donor keeps one), and a replace tears the old one down.
  */
 export function createLiveEnvelopesComputable(
   sharedTree: SynchronizedTreeState,
 ): Computable<LiveEnvelope[] | undefined> {
-  return Computable.make((ctx) => {
-    const roots = ctx.accessor(sharedTree.rootsEntry()).nodes();
-    const result: LiveEnvelope[] = [];
-    for (const envelope of roots) {
-      if (envelope === undefined) continue;
-      if (!resourceTypesEqual(envelope.resourceType, SharedEnvelopeResourceType)) continue;
-      const data = normalizeEnvelopeData(envelope.getDataAsJson<unknown>());
-      // Same recognise-or-hide rule as the pending view, and for the same envelope: hiding an
-      // offer while accept could still resolve it would only move the problem.
-      if (data === undefined) continue;
-      result.push({ rid: envelope.id, data });
-    }
-    return result;
-  });
+  return Computable.make((ctx) => decodedEnvelopes(ctx.accessor(sharedTree.rootsEntry()).nodes()));
 }
 
 /**
- * Builds the {@link PendingShare} computable over the shared-resource discovery tree, filtered
- * against the set of already-handled shareIds (those with a decision/{shareId} in the acceptor's
- * SharingState). Both trees feed one Computable so it recomputes when either changes.
+ * Builds the {@link AvailableShare} computable over the shared-resource discovery tree, marking
+ * each entry with whether this user has hidden it (a hiddenField in their own SharingState).
+ * Both trees feed one Computable so it recomputes when either changes.
  *
  * `currentUserLogin` (when known) suppresses the user's own shares: a share-with-everybody grants
- * the everyone-user, so the donor discovers their own envelope as a pending share. There is no
- * scenario where a user accepts their own share, so they are dropped from the pending view.
+ * the everyone-user, so the donor discovers their own envelope here. A donor already owns what
+ * they shared, so their own envelopes are dropped from this view.
  */
-export function createPendingSharesComputable(
+export function createAvailableSharesComputable(
   sharedTree: SynchronizedTreeState,
   sharingStateTree: SynchronizedTreeState,
   currentUserLogin: string | null,
-): Computable<PendingShare[] | undefined> {
+): Computable<AvailableShare[] | undefined> {
   return Computable.make((ctx) => {
-    const roots = ctx.accessor(sharedTree.rootsEntry()).nodes();
-
-    // Set of shareIds already handled (accepted or rejected) — dedup discovery on the logical share.
+    // Shares this user has put out of sight, keyed on the share. A share replaced by a newer one
+    // is a new share, so its replacement arrives unhidden.
     const stateNode = ctx.accessor(sharingStateTree.entry()).node();
-    const handled = new Set<ShareId>();
+    const hidden = new Set<ShareId>();
     if (stateNode !== undefined)
       for (const f of stateNode.listDynamicFields())
-        if (f.startsWith(DecisionFieldPrefix))
-          handled.add(asShareId(f.slice(DecisionFieldPrefix.length)));
+        if (isHiddenField(f)) hidden.add(hiddenFieldShareId(f));
 
-    const result: PendingShare[] = [];
-    for (const envelope of roots) {
-      if (envelope === undefined) continue;
-      if (!resourceTypesEqual(envelope.resourceType, SharedEnvelopeResourceType)) continue;
-      const data = normalizeEnvelopeData(envelope.getDataAsJson<unknown>());
-      // An envelope whose schemaVersion or payload kind this build does not know is hidden, not
-      // offered: there is nothing useful to do with a share we cannot read.
-      if (data === undefined) continue;
-      if (handled.has(data.shareId)) continue; // already accepted or rejected
+    const result: AvailableShare[] = [];
+    for (const { data } of decodedEnvelopes(ctx.accessor(sharedTree.rootsEntry()).nodes())) {
       if (currentUserLogin !== null && data.sender === currentUserLogin) continue; // own share
       if (data.expiresAt !== null && data.expiresAt <= Date.now()) continue;
 
+      const folder = envelopeFolderSummary(data);
+      const description = envelopeDescription(data);
       result.push({
         shareId: data.shareId,
         sender: data.sender,
@@ -334,6 +282,9 @@ export function createPendingSharesComputable(
         mode: data.mode,
         payloadKind: data.payload.kind,
         grantedAt: data.sharedAt,
+        ...(description === undefined ? {} : { description }),
+        ...(folder === undefined ? {} : { folder }),
+        hidden: hidden.has(data.shareId),
       });
     }
     result.sort((a, b) => b.grantedAt - a.grantedAt);
@@ -341,15 +292,7 @@ export function createPendingSharesComputable(
   });
 }
 
-const SharingStatePruningFunction: PruningFunction = (resource) => {
-  if (!resourceTypesEqual(resource.type, SharingStateResourceType)) return [];
-  return resource.fields;
-};
-
-// decision/{shareId} values are leaf JSON resources; follow fields only from SharingState.
-const SharingStateFieldFilter: Filter = treeFilter.resourceTypeEq(SharingStateResourceType.name);
-
-/** Creates the acceptor's SharingState synchronized tree (single explicit root). */
+/** Creates the recipient's SharingState synchronized tree (single explicit root). */
 export async function createSharingStateTree(
   pl: PlClient,
   stateRid: SignedResourceId,
@@ -367,7 +310,120 @@ export async function createSharingStateTree(
   );
 }
 
-/** Maps an envelope resource id (signed) to its string form, for failure reporting. */
-export function envelopeIdString(rid: SignedResourceId): string {
-  return resourceIdToString(rid);
+//
+// Internals
+//
+
+const SharingOutboxPruningFunction: PruningFunction = (resource) => {
+  if (
+    !resourceTypesEqual(resource.type, SharingOutboxResourceType) &&
+    !resourceTypesEqual(resource.type, SharedEnvelopeResourceType)
+  )
+    return [];
+  return resource.fields;
+};
+
+// Server-side traversal scope (modern resourceTree path). Pruning is client-side ONLY and does
+// NOT stop the backend walk — without a fieldFilter the backend descends through the envelope's
+// project/{uuid} snapshots into the whole project graph (StreamManager etc.), whose field-driven
+// finality predicate then throws on the pruned-to-[] fields. Following fields only FROM the outbox
+// and the envelope stops the walk at the project snapshots (UserProject), which we never traverse.
+const SharingOutboxFieldFilter: Filter = treeFilter.or(
+  treeFilter.resourceTypeEq(SharingOutboxResourceType.name),
+  treeFilter.resourceTypeEq(SharedEnvelopeResourceType.name),
+);
+
+const SharedEnvelopePruningFunction: PruningFunction = (resource) => {
+  if (!resourceTypesEqual(resource.type, SharedEnvelopeResourceType)) return [];
+  return resource.fields;
+};
+
+// Discovery only needs each envelope's immutable EnvelopeData (basic resource data); it must NOT
+// descend into the project snapshots. Following fields only FROM the envelope stops the walk at
+// the UserProject snapshots (their fields are never followed).
+const AvailableSharesFieldFilter: Filter = treeFilter.resourceTypeEq(
+  SharedEnvelopeResourceType.name,
+);
+
+const SharingStatePruningFunction: PruningFunction = (resource) => {
+  if (!resourceTypesEqual(resource.type, SharingStateResourceType)) return [];
+  return resource.fields;
+};
+
+// decision/{shareId} values are leaf JSON resources; follow fields only from SharingState.
+const SharingStateFieldFilter: Filter = treeFilter.resourceTypeEq(SharingStateResourceType.name);
+
+/** Intermediate of an outgoing share before its full recipient list is fetched: everything the
+ *  tree carries synchronously, plus the envelope's signed id for the async `ListGrants` enrich. */
+type OutgoingShareDraft = Omit<OutgoingShare, "recipients"> & { envelopeRid: SignedResourceId };
+
+/**
+ * Every envelope among the discovery tree's roots that this build can read, decoded. A root that
+ * is not a {@link SharedEnvelopeResourceType}, or whose schemaVersion or payload kind this build
+ * does not know, is left out rather than offered: there is nothing useful to do with a share that
+ * cannot be read.
+ */
+function decodedEnvelopes(roots: readonly (PlTreeNodeAccessor | undefined)[]): LiveEnvelope[] {
+  const result: LiveEnvelope[] = [];
+  for (const envelope of roots) {
+    if (envelope === undefined) continue;
+    if (!resourceTypesEqual(envelope.resourceType, SharedEnvelopeResourceType)) continue;
+    const data = normalizeEnvelopeData(envelope.getDataAsJson<unknown>());
+    if (data === undefined) continue;
+    result.push({ rid: envelope.id, data });
+  }
+  return result;
+}
+
+/** Per-project view for the donor, from the envelope's `projects` payload; empty for a payload
+ *  that carries no project. */
+function envelopeProjects(data: EnvelopeData): OutgoingShare["projects"] {
+  return Object.values(envelopeProjectMap(data)).map((p) => ({
+    projectId: p.source,
+    label: p.label,
+    updatedAt: p.updatedAt,
+  }));
+}
+
+/**
+ * What a folder share is, in the words both lists show it in: the shared folder's name and how
+ * much is inside. `undefined` for any other payload.
+ *
+ * The root folder is excluded from `folderCount` — it is the thing being described, not something
+ * inside it. A folder envelope with no single root is one nothing can be rebuilt from, and it is
+ * described as nothing rather than guessed at.
+ */
+function envelopeFolderSummary(data: EnvelopeData): EnvelopeFolderSummary | undefined {
+  if (data.payload.kind !== "folder") return undefined;
+  const { folders, projects, templates } = data.payload;
+  const root = envelopeFolderRoot(folders);
+  if (root === undefined) return undefined;
+  return {
+    label: folders[root].name,
+    source: data.payload.source,
+    folderCount: Object.keys(folders).length - 1,
+    projectCount: Object.keys(projects).length,
+    templateCount: templates.length,
+  };
+}
+
+/**
+ * What the shared thing says about itself: the template's description, the root folder's, or the
+ * one project's of a single-project share. `undefined` when it has none, for a pack of several
+ * projects, which describes no single thing, and for a folder envelope with no single root.
+ */
+function envelopeDescription(data: EnvelopeData): string | undefined {
+  const payload = data.payload;
+  switch (payload.kind) {
+    case "template":
+      return payload.description;
+    case "folder": {
+      const root = envelopeFolderRoot(payload.folders);
+      return root === undefined ? undefined : payload.folders[root].description;
+    }
+    case "projects": {
+      const projects = Object.values(payload.projects);
+      return projects.length === 1 ? projects[0]?.description : undefined;
+    }
+  }
 }

package/src/middle_layer/template_list.test.ts

@@ -0,0 +1,148 @@
+/**
+ * The template-list reader against a hand-built templates resource: what it keeps, what it skips
+ * and in which order. No backend — `templateListEntries` is the whole computable body, fed here
+ * with a stand-in node instead of a synchronized tree.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { ResourceType } from "@milaboratories/pl-client";
+import { asSignedResourceId } from "@milaboratories/pl-client";
+import type { BlockKindSelectorReference } from "@milaboratories/pl-model-common";
+import { PROJECT_TEMPLATE_SCHEMA_V1 } from "@milaboratories/pl-model-common";
+import type { StoredTemplateData } from "./template_list";
+import {
+  TemplateCreatedTimestamp,
+  TemplateDescriptionKey,
+  TemplateLabelKey,
+  TemplateResourceType,
+  templateListEntries,
+} from "./template_list";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** One field of the templates resource: a node, or a field that resolves to nothing. */
+interface Entry {
+  readonly field: string;
+  readonly id?: number;
+  readonly type?: ResourceType;
+  readonly data?: StoredTemplateData;
+  readonly kv?: Record<string, unknown>;
+  /** A field whose value has not resolved yet — `traverse` returns undefined. */
+  readonly unresolved?: boolean;
+}
+
+/** A stored document listing the given number of blocks; only its length is read. */
+function stored(blocks: number): StoredTemplateData {
+  return {
+    schemaVersion: 1,
+    document: {
+      schema: PROJECT_TEMPLATE_SCHEMA_V1,
+      blocks: Array.from({ length: blocks }, (_, i) => ({
+        id: `block-${i}`,
+        kind: KIND,
+        params: {},
+      })),
+    },
+  };
+}
+
+const KIND = "@platforma-open/milaboratories.demo.kind@^1.0.0" as BlockKindSelectorReference;
+
+/** A template field with the data and metadata a synced template carries. */
+function template(field: string, id: number, label: string, created: number) {
+  return {
+    field,
+    id,
+    type: TemplateResourceType,
+    data: stored(2),
+    kv: { [TemplateLabelKey]: label, [TemplateCreatedTimestamp]: created },
+  } satisfies Entry;
+}
+
+/** Stand-in for the templates-list tree node, carrying exactly what the reader reads. */
+function templatesNode(...entries: Entry[]) {
+  return {
+    listDynamicFields: () => entries.map((e) => e.field),
+    traverse: (fieldName: string) => {
+      const entry = entries.find((e) => e.field === fieldName);
+      if (entry === undefined || entry.unresolved) return undefined;
+      return {
+        id: asSignedResourceId(`0x${(entry.id ?? 0).toString(16)}|ab`),
+        resourceType: entry.type ?? TemplateResourceType,
+        getDataAsJson: <T>() => entry.data as T | undefined,
+        getKeyValueAsJson: <T>(key: string) => (entry.kv ?? {})[key] as T | undefined,
+      };
+    },
+  };
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("tolerance", () => {
+  it("keeps every synced template", () => {
+    const entries = templateListEntries(
+      templatesNode(template("uuid-a", 1, "A", 100), template("uuid-b", 2, "B", 200)),
+    );
+
+    expect(entries.map((e) => e.label)).toStrictEqual(["B", "A"]);
+    expect(entries[1].created).toStrictEqual(new Date(100));
+    expect(entries[1].blockCount).toBe(2);
+  });
+
+  it("skips a sibling that is not a template, and keeps the templates around it", () => {
+    const entries = templateListEntries(
+      templatesNode(
+        template("uuid-a", 1, "A", 100),
+        { field: "stray", id: 9, type: { name: "Folders", version: "1" }, data: stored(1) },
+        template("uuid-b", 2, "B", 200),
+      ),
+    );
+
+    expect(entries.map((e) => e.label)).toStrictEqual(["B", "A"]);
+  });
+
+  it("skips a template whose data or metadata has not synced yet", () => {
+    const halfSynced: { name: string; data?: StoredTemplateData; kv: Record<string, unknown> }[] = [
+      { name: "data missing", kv: { [TemplateLabelKey]: "x", [TemplateCreatedTimestamp]: 1 } },
+      { name: "label missing", data: stored(1), kv: { [TemplateCreatedTimestamp]: 1 } },
+      { name: "created missing", data: stored(1), kv: { [TemplateLabelKey]: "x" } },
+    ];
+
+    for (const { name, data, kv } of halfSynced) {
+      const entries = templateListEntries(
+        templatesNode(
+          { field: "uuid-half", id: 9, type: TemplateResourceType, data, kv },
+          template("uuid-a", 1, "A", 100),
+        ),
+      );
+      expect(
+        entries.map((e) => e.label),
+        name,
+      ).toStrictEqual(["A"]);
+    }
+  });
+
+  it("skips a field that resolves to nothing", () => {
+    const entries = templateListEntries(
+      templatesNode({ field: "uuid-pending", unresolved: true }, template("uuid-a", 1, "A", 1)),
+    );
+
+    expect(entries.map((e) => e.label)).toStrictEqual(["A"]);
+  });
+});
+
+describe("description", () => {
+  it("carries a description, and reads a blank one as none", () => {
+    const described = template("uuid-a", 1, "A", 100);
+    const blank = template("uuid-b", 2, "B", 200);
+    const entries = templateListEntries(
+      templatesNode(
+        { ...described, kv: { ...described.kv, [TemplateDescriptionKey]: "  Plates  " } },
+        { ...blank, kv: { ...blank.kv, [TemplateDescriptionKey]: "   " } },
+      ),
+    );
+
+    expect(entries.find((e) => e.label === "A")?.description).toBe("Plates");
+    expect(entries.find((e) => e.label === "B")).not.toHaveProperty("description");
+  });
+});