cursedbelt 3.0.2 → 4.0.0

package/src/react/media-gallery/MediaMetaEditor.tsx

@@ -0,0 +1,237 @@
+import React from 'react';
+import { ActionBar } from '../components/ActionBar';
+import { AutoGrowTextarea } from '../components/AutoGrowTextarea';
+import { Button } from '../components/Button';
+import { FieldLabel } from '../components/FieldLabel';
+import { InfoHint } from '../components/InfoHint';
+import { Modal } from '../components/Modal';
+import { TagsInput } from '../components/TagsInput';
+import {
+  type MediaMetaChange,
+  cleanTags,
+  isEmptyMetaChange,
+  tagDiff,
+  tagsOn,
+} from './mediaMeta';
+import type { MediaGalleryItem } from './types';
+
+/**
+ * Tag media, and say what it is — the dialog.
+ *
+ * ── The owner's ask, `ideas/collections-09-14.md`, 2026-09-14 ──────────────────────────
+ * *"In media galleries have an option for apps to tag media and aadd descriptions to media."*
+ *
+ * The gallery could already READ `tags` — the tile prints the first three and the chips filter
+ * on them — and had no way to write one and no description field at all. So the capability
+ * that was missing is authoring, and like every other one on this component it arrives as a
+ * HANDLER: pass `onSaveMeta` and the control appears, pass nothing and this dialog is not even
+ * in the bundle. See `MediaGalleryProps.onSaveMeta`, and `onTrimVideo` for the rule stated in
+ * full.
+ *
+ * ── 🔴 One item and forty are the SAME dialog, and not the same form ──────────────────
+ * Forty photographs do not share one tag list, so "here are the new tags" cannot be a single
+ * array — it would wipe thirty-nine lists nobody looked at. Over a selection the two fields
+ * are therefore ADD and REMOVE, which mean the same thing for one item as for forty and reach
+ * the app as one call carrying every id (`mediaMeta.ts` explains the shape).
+ *
+ * The description is deliberately absent from the bulk form. One sentence cannot describe
+ * forty files, and a field that writes the same words onto all of them is a field whose only
+ * correct use is the one nobody wants.
+ *
+ * ── Why the vocabulary is offered rather than typed ───────────────────────────────────
+ * `suggestions` is every tag already in the gallery, handed to `TagsInput`'s native
+ * `<datalist>`. Re-typing `holiday` is how `Holiday` and `holidays` get minted beside it, and
+ * three spellings of one tag is three filter chips that each find a third of the album. The
+ * model matches case-insensitively for the same reason; this is the half that stops it
+ * happening at the keyboard rather than cleaning up afterwards.
+ */
+export interface MediaMetaEditorProps {
+  /** What is being tagged. One item opens the single form; two or more open the bulk one. */
+  items: readonly MediaGalleryItem[];
+  /** Every tag already in use in this gallery, offered as you type. */
+  suggestions?: readonly string[];
+  open?: boolean;
+  onClose: () => void;
+  /**
+   * Save. Resolving CLOSES the dialog; rejecting leaves it open with the draft intact,
+   * because a failed request must not cost somebody the tags they just typed.
+   */
+  onSubmit: (change: MediaMetaChange) => void | Promise<void>;
+}
+
+export function MediaMetaEditor({
+  items,
+  suggestions,
+  open = true,
+  onClose,
+  onSubmit,
+}: MediaMetaEditorProps) {
+  const single = items.length === 1 ? items[0] : undefined;
+  const [tags, setTags] = React.useState<string[]>(() => cleanTags(single?.tags ?? []));
+  const [description, setDescription] = React.useState(() => single?.description ?? '');
+  const [addTags, setAddTags] = React.useState<string[]>([]);
+  const [removeTags, setRemoveTags] = React.useState<string[]>([]);
+  const [saving, setSaving] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+
+  /** The tags on the selection — the only ones a Remove can act on. */
+  const onSelection = React.useMemo(() => tagsOn(items), [items]);
+
+  const change: MediaMetaChange = React.useMemo(() => {
+    if (single) {
+      const diff = tagDiff(single.tags, tags);
+      const next = description.trim();
+      return next === (single.description ?? '').trim()
+        ? diff
+        : { ...diff, description: next };
+    }
+    return { addTags: cleanTags(addTags), removeTags: cleanTags(removeTags) };
+  }, [single, tags, description, addTags, removeTags]);
+
+  const nothingToDo = isEmptyMetaChange(change);
+
+  const submit = async (): Promise<void> => {
+    if (nothingToDo) return;
+    setSaving(true);
+    setError(null);
+    try {
+      await onSubmit(change);
+      onClose();
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : 'That could not be saved.');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const what =
+    single?.name ?? `${items.length} item${items.length === 1 ? '' : 's'}`;
+
+  return (
+    <Modal
+      open={open}
+      onClose={onClose}
+      title={single ? `Tags and description — ${single.name}` : `Tag ${what}`}
+      subtitle={
+        single
+          ? 'Tags put this file on a filter chip; the description shows under the title.'
+          : 'Added to every item you ticked, in one go — nothing else about them changes.'
+      }
+      size='md'
+      // 🔴 The discard guard. This body is nothing but text fields, so a backdrop click
+      // without it throws away every tag typed since the dialog opened, with no prompt.
+      isDirty={!nothingToDo}
+      {...(error ? { problem: error } : {})}
+      footer={
+        <ActionBar
+          primary={
+            <>
+              <Button variant='secondary' onClick={onClose} tooltip='Close without saving anything'>
+                Cancel
+              </Button>
+              <Button
+                onClick={() => void submit()}
+                disabled={saving || nothingToDo}
+                tooltip={
+                  nothingToDo
+                    ? 'Nothing has changed yet'
+                    : single
+                      ? 'Save these tags and this description'
+                      : `Apply this to all ${items.length} items in one go`
+                }
+              >
+                {saving ? 'Saving…' : 'Save'}
+              </Button>
+            </>
+          }
+        />
+      }
+    >
+      <div className='cbmm'>
+        {single ? (
+          <>
+            <div className='cbmm-field'>
+              <FieldLabel
+                hint={
+                  <>
+                    Tags are how this file is found again: each one becomes a chip above the
+                    grid that filters the album down to the things wearing it. Type and press{' '}
+                    <kbd>Enter</kbd>, or pick one already in use.
+                  </>
+                }
+              >
+                Tags
+              </FieldLabel>
+              <TagsInput
+                value={tags}
+                onChange={setTags}
+                aria-label={`Tags for ${single.name}`}
+                placeholder='Add a tag…'
+                {...(suggestions ? { suggestions } : {})}
+              />
+            </div>
+            <div className='cbmm-field'>
+              <FieldLabel>Description</FieldLabel>
+              <AutoGrowTextarea
+                value={description}
+                onChange={(event) => setDescription(event.currentTarget.value)}
+                aria-label={`Description of ${single.name}`}
+                placeholder='What is this, and why did you keep it?'
+                maxLength={2_000}
+              />
+            </div>
+          </>
+        ) : (
+          <>
+            <p className='cbmm-count'>
+              {items.length} items ticked.
+              <InfoHint title='Tagging a selection' align='right'>
+                <p>
+                  Whatever you add here is added to <strong>every</strong> item you ticked, and
+                  whatever you remove is removed from all of them — one request, not one per
+                  file.
+                </p>
+                <p>
+                  Tags each item already has are left alone, and a tag that differs only in
+                  capitalisation from one it already has is not added twice.
+                </p>
+                <p>
+                  There is no description field here on purpose: one sentence cannot describe
+                  several files. Open one on its own to describe it.
+                </p>
+              </InfoHint>
+            </p>
+            <div className='cbmm-field'>
+              <FieldLabel>Add tags</FieldLabel>
+              <TagsInput
+                value={addTags}
+                onChange={setAddTags}
+                aria-label={`Tags to add to all ${items.length} selected items`}
+                placeholder='Add a tag to all of them…'
+                {...(suggestions ? { suggestions } : {})}
+              />
+            </div>
+            <div className='cbmm-field'>
+              <FieldLabel>Remove tags</FieldLabel>
+              <TagsInput
+                value={removeTags}
+                onChange={setRemoveTags}
+                aria-label={`Tags to remove from all ${items.length} selected items`}
+                placeholder={
+                  onSelection.length > 0
+                    ? 'Take a tag off all of them…'
+                    : 'None of these have a tag yet'
+                }
+                disabled={onSelection.length === 0}
+                // Only what is actually ON the selection: offering the whole album's
+                // vocabulary here would invite removing a tag none of these items carries,
+                // which is a request that does nothing and reads as a broken control.
+                suggestions={onSelection}
+              />
+            </div>
+          </>
+        )}
+      </div>
+    </Modal>
+  );
+}

package/src/react/media-gallery/galleryTable.spec.ts

@@ -1,6 +1,12 @@
 import { describe, expect, test } from 'bun:test';
 import { readFileSync } from 'node:fs';
-import { GALLERY_TABLE_ROW_HEIGHT, durationLabel, visibleWindow } from './GalleryTable';
+import { formatBytes } from 'cwip/format';
+import {
+  GALLERY_TABLE_ROW_HEIGHT,
+  durationLabel,
+  exactBytesLabel,
+  visibleWindow,
+} from './GalleryTable';
 
 /**
  * The table's arithmetic, tested where a browser is not needed.
@@ -56,3 +62,37 @@ describe('GalleryTable — durations', () => {
     expect(durationLabel(Number.NaN)).toBeNull();
   });
 });
+
+/**
+ * The exact-bytes column's label.
+ *
+ * 🔴 The first test here is the WHOLE ask, and it was red before this column existed:
+ * *"I want to see the exact file size in bytes … so I can easily tell if two files are the
+ * exact same byte size to help me know if they are duplicates or not."* `formatBytes` — the
+ * Size column beside it — renders both of these files as `1.4 GB`.
+ */
+describe('GalleryTable — exact bytes', () => {
+  test('🔴 two files one byte apart read differently, which `formatBytes` cannot manage', () => {
+    const a = 1_402_653_184;
+    const b = a + 1;
+    expect(exactBytesLabel(a)).not.toBe(exactBytesLabel(b));
+    // …and the same two through the rounded column, which is why this column exists.
+    expect(formatBytes(a)).toBe(formatBytes(b));
+  });
+
+  test('the digits are grouped, because ten in a row are not comparable at a glance', () => {
+    // The separator is the reader's locale's (a space in fr-FR, a comma in en-US), so the
+    // assertion is on the GROUPING rather than on the character — the digits, in order, in
+    // threes. Pinning a comma here would be this spec asserting the test machine's locale.
+    expect(exactBytesLabel(1_402_653_184)).toMatch(/^1\D?402\D?653\D?184$/);
+    // Under four digits there is nothing to group, and nothing is invented.
+    expect(exactBytesLabel(512)).toBe('512');
+    expect(exactBytesLabel(0)).toBe('0');
+  });
+
+  test('null for a row with no size, so the cell shows the same — every column does', () => {
+    expect(exactBytesLabel(undefined)).toBeNull();
+    expect(exactBytesLabel(Number.NaN)).toBeNull();
+    expect(exactBytesLabel(Number.POSITIVE_INFINITY)).toBeNull();
+  });
+});

package/src/react/media-gallery/index.ts

@@ -24,9 +24,16 @@ export {
   sortGalleryItems,
 } from './mediaGalleryModel';
 export type { MediaGalleryItem, MediaGalleryItemMedia, MediaGalleryOrder } from './types';
+// `onSaveMeta`'s contract, and the merge every consumer of it would otherwise write itself.
+// Exported for the same reason `fileTreeSelection.ts`'s rules are: the gallery persists
+// nothing, so the "add these, remove those, keep the spelling" arithmetic happens in the app —
+// and four apps re-deriving it is four chances to mint `Holiday` beside `holiday`.
+export { type MediaMetaChange, applyMetaChange } from './mediaMeta';
 // Re-exported so an app wiring `onTrimVideo` types its handler from the gallery's own subpath
 // rather than reaching into `cursedbelt/react/media` for one interface.
 export type { VideoCut } from 'cursedbelt-core/media/video-cuts';
+// Same reason for `onSaveChapters`: an app types its handler from the gallery's own subpath.
+export type { VideoChapter } from '../media/videoChapters';
 // The open file, in the URL. A BINDING over `cursedbelt/react/deep-link`, not a second way
 // of writing one — see the header of `galleryDeepLink.ts`.
 export {

package/src/react/media-gallery/mediaGallery.css

@@ -177,12 +177,52 @@
 	container-type: size;
 }
 
+/* 🔴 The turned picture surface is SIZED to the swapped panel, not merely bounded by it.
+   Owner, `ideas/collections-09-14.md`: *"If I rotate a portait style video 90 degrees it should
+   be changed to fit the wide screen panel … so I can watch it like it was recorded with wide
+   screen."* — a rotation on its own leaves the footage the size it already was.
+
+   These used to be `max-block-size`/`max-inline-size`, which can only SHRINK. Measured in
+   Chromium on 2026-09-16 against `demo`'s 9:16 clip in a 505×284 panel: the player gives its
+   `<video>` a 16:9 box of its own (284×160 there), `object-fit: contain` draws the portrait
+   film as a 90×160 pillar inside it, and the max-* pair had nothing to bind on — so the turn
+   painted 160×90 of film in a 505×284 panel, which is the tall thin picture in the middle of a
+   black stage that was reported. `e2e/video-turn.spec.ts` measures exactly that rectangle.
+
+   Width from the container's BLOCK size and height from its INLINE size — the axis swap, said
+   in the only units that can say it — so after the rotation the box is the panel again. The
+   fit itself is then `object-fit: contain`'s, which is what keeps this honest for footage whose
+   aspect is not the panel's inverse: a 16:9 clip turned on its end is letterboxed whole rather
+   than blown up and cropped, and a square one is left alone. A scale factor on the transform
+   cannot make that distinction — it does not know the film's shape — which is why the fit lives
+   on the box and only the rotation travels in `--cbmg-turn`. */
 .cbmg-stage-turn[data-turned='true'] video,
 .cbmg-stage-turn[data-turned='true'] .vds-poster img {
 	max-width: none;
 	max-height: none;
-	max-block-size: 100cqi;
-	max-inline-size: 100cqb;
+	max-block-size: none;
+	max-inline-size: none;
+	width: 100cqb;
+	height: 100cqi;
+	/* The player sets its own 16:9 on the element; an explicit pair of sides must win over it,
+	   or the swap above is computed and then thrown away. */
+	aspect-ratio: auto;
+	object-fit: contain;
+}
+
+/* 🔴 …and it has to be turned about the PANEL's centre, which means it has to sit at it first.
+   A rotation pivots on the element's own middle, so an element the player has left against the
+   left edge of its provider box lands a quarter of the panel off to one side — measured in
+   Chromium on 2026-09-16: a correctly sized 505×284 of film, painted at x=278 in a panel
+   starting at x=388, i.e. 110px of it outside the frame and a black band the same width down
+   the other edge. The wrapper above centres what IS its child; on the Vidstack path the child
+   is the player, and the element being turned is two boxes further in. Same reach as
+   `.vds-poster` / `.vds-controls` elsewhere in this file, and inert on the native stage, whose
+   `<video>` is already the wrapper's own flex-centred child. */
+.cbmg-stage-turn[data-turned='true'] [data-media-provider] {
+	display: flex;
+	align-items: center;
+	justify-content: center;
 }
 
 /* Inside the turned frame the stage element must stop claiming its own 70vh, or the flex
@@ -322,6 +362,63 @@
 	background: color-mix(in srgb, var(--accent-solid) 12%, transparent);
 }
 
+/* ── The tile the STAGE is showing ───────────────────────────────────────────────────────
+ *
+ * Owner, `ideas/collections-09-14.md`: *"I want to … still see the playing video in the list
+ * and nothing about the list changes as I pick other videos."* The strip under the stage used
+ * to drop the open file; it keeps it now and marks it here.
+ *
+ * 🔴 `::before`, where the selection tint is `::after`, so a tile that is BOTH ticked and
+ * playing draws both marks instead of one silently replacing the other. Neither pseudo is a
+ * `:first-child`, so `.cbmg-selectable > :first-child { height: 100% }` above is untouched.
+ */
+.cbmg-selectable.is-playing::before {
+	content: '';
+	position: absolute;
+	inset: 0;
+	/* guardrails-ignore no-raw-zindex: the same tile-local stacking the selection tint uses —
+	   the mark over its own tile, inside the isolated `.cbmg-selectable` context. */
+	z-index: 1;
+	pointer-events: none;
+	border-radius: 8px;
+	/* Thicker than the selection's 2px: this one has to be findable while scrolling past it,
+	   which is the whole reason the tile stays in the list. */
+	outline: 3px solid var(--accent-solid);
+	outline-offset: -3px;
+	background: color-mix(in srgb, var(--accent-solid) 10%, transparent);
+}
+/* A filled capsule with its own foreground token (DESIGN.md §3 — never a thin outline), at
+   the 12px floor (§4). `pointer-events: none` because the whole tile is one button and a
+   label that swallowed the click would make its corner dead. */
+.cbmg-playing-chip {
+	position: absolute;
+	top: 6px;
+	left: 6px;
+	/* guardrails-ignore no-raw-zindex: tile-local stacking, over this tile's own mark. */
+	z-index: 2;
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+	max-width: calc(100% - 12px);
+	padding: 3px 8px;
+	border-radius: 999px;
+	background: var(--accent-solid);
+	color: var(--accent-solid-foreground);
+	font-size: 12px;
+	font-weight: 600;
+	line-height: 1.2;
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	pointer-events: none;
+}
+/* The one corner collision: a document tile draws its type badge in this exact spot. The mark
+   wins for as long as it is there — the stage directly above is showing the file, and its
+   titlebar says what kind it is, so the badge is the redundant one of the two. */
+.cbmg-selectable.is-playing .cbmg-doc-badge {
+	display: none;
+}
+
 .cbmg-bulkbar {
 	display: flex;
 	align-items: center;
@@ -356,7 +453,7 @@
    frame grabber were each written inside ONE app's `detailActions`; these are the rules that
    came with them. Plain CSS under `.cbmg-`, like the rest of this file. */
 
-/* 🔴 The ☀ Picture adjustment reaches the stage through a custom property set on the stage
+/* 🔴 The Picture adjustment reaches the stage through a custom property set on the stage
    anchor, NOT through a prop threaded into the player — the video stage is Vidstack's and is
    several components deep, so a prop would make every consumer of the player primitive learn
    about a control only the gallery offers.
@@ -544,6 +641,21 @@
 	box-shadow: inset 3px 0 0 0 var(--accent);
 }
 
+/* The row the stage is showing — the table's half of the grid tile's mark. Same shape as the
+   selected row so the two read as one family, and a step louder (the SOLID accent, a 4px bar)
+   because there is exactly one of these and it is the row the reader is looking for.
+   The name it is given is `.cbgd-sr-only` text in the name cell; `GalleryTable.tsx` says why a
+   visible capsule cannot live in a fixed-layout cell. */
+.cbgt-row.is-playing {
+	background: color-mix(in srgb, var(--accent-solid) 12%, transparent);
+	box-shadow: inset 4px 0 0 0 var(--accent-solid);
+}
+/* …and it keeps that reading under the pointer, which the hover rule above would otherwise
+   take away by painting the plain hover fill over it. */
+.cbgt-row.is-playing:hover {
+	background: color-mix(in srgb, var(--accent-solid) 18%, transparent);
+}
+
 /* Fixed tracks, declared once. `table-layout: fixed` means these widths are the layout. */
 .cbgt-cell--check {
 	width: 36px;
@@ -566,6 +678,14 @@
 .cbgt-cell--length {
 	width: 78px;
 }
+/* The exact byte count. Wider than the rounded Size beside it because the whole point of the
+   column is that nothing is dropped: a terabyte is 13 digits plus 4 separators, and a count
+   that truncated to "1,402,653,1…" would be exactly as useless for telling two files apart as
+   the rounded "1.4 GB" it exists to replace. `.cbgt-cell--num` already right-aligns it and
+   gives it tabular figures, which is what makes two counts comparable down a column. */
+.cbgt-cell--bytes {
+	width: 132px;
+}
 /* The date is the widest of the three numeric columns: "21 Aug 2026" at 12px does not fit
    the 96px the others use, and a DATE that truncates to "Aug 21, 2…" is a column that has
    stopped answering the question it exists for. Deliberately generous — every locale this
@@ -731,7 +851,14 @@
 /* ── Narrow screens ──────────────────────────────────────────────────────────────────────
  *
  * Kind and Length are the two columns a phone can lose without the row stopping being
- * useful — the name, the size and the date are what the owner is scanning for. */
+ * useful — the name, the size and the date are what the owner is scanning for.
+ *
+ * 🔴 The exact-bytes column goes with them, and it is the one that would hurt most to keep:
+ * it is the widest track in the table (132px), and these widths ARE the layout under
+ * `table-layout: fixed` — thumb + size + bytes + date already exceeds a 390px phone on their
+ * own, so keeping it would trade the file NAME for a digit count. The rounded Size stays, so
+ * the row still answers "how big"; comparing two counts to the byte is a desk instrument, and
+ * the desk is where the column is. */
 @media (max-width: 720px) {
 	.cbgt-head th:first-child,
 	.cbgt-row td:first-child {
@@ -742,6 +869,7 @@
 		padding-right: 12px;
 	}
 	.cbgt-cell--kind,
+	.cbgt-cell--bytes,
 	.cbgt-cell--length {
 		display: none;
 	}
@@ -782,3 +910,51 @@
 	min-width: 0;
 	min-height: 0;
 }
+
+/*
+ * ── The DESCRIPTION, under the title on the stage ───────────────────────────────────────
+ *
+ * Owner, `ideas/collections-09-14.md`: *"In media galleries have an option for apps to tag
+ * media and aadd descriptions to media."*
+ *
+ * 🔴 It cannot ride the ` · ` facts line. `.cbgd-meta-line` is `white-space: nowrap` with an
+ * ellipsis because the SAME class captions every tile in the grid, so a sentence appended
+ * there is a sentence nobody can read past its first few words. These two rules are what let
+ * the titlebar's own wrapping flex row carry a second, wrapping line — the facts keep the
+ * nowrap behaviour they have always had, and the description is a block beneath them.
+ *
+ * The width cap is readability, not decoration: `DESIGN.md` §4 asks for a measure, and a
+ * description running the full width of a 1680px stage is one line of 200 characters.
+ */
+.cbmg-stage-facts {
+	display: block;
+}
+.cbmg-stage-description {
+	display: block;
+	/* Overrides the nowrap/ellipsis inherited from `.cbgd-meta-line` — see above. */
+	white-space: normal;
+	max-width: 68ch;
+	margin-top: 2px;
+	font-size: 12px;
+	line-height: 1.45;
+	color: var(--muted-foreground);
+}
+
+/*
+ * The tag/description editor's body — see `MediaMetaEditor.tsx`. Plain CSS in this module's
+ * own stylesheet rather than utilities on the elements, for the reason the rest of this file
+ * records: the sheet is already loaded wherever the gallery is, and the dialog is otherwise
+ * built entirely from design-system components that bring their own chrome.
+ */
+.cbmm {
+	display: flex;
+	flex-direction: column;
+	gap: 14px;
+}
+.cbmm-count {
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	font-size: 13px;
+	color: var(--muted-foreground);
+}

package/src/react/media-gallery/mediaMeta.spec.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  applyMetaChange,
+  cleanTags,
+  isEmptyMetaChange,
+  tagDiff,
+  tagsOn,
+} from './mediaMeta';
+
+describe('cleanTags', () => {
+  test('trims, drops empties and keeps the first spelling of a case-duplicate', () => {
+    expect(cleanTags([' holiday ', '', '   ', 'Holiday', 'beach'])).toEqual([
+      'holiday',
+      'beach',
+    ]);
+  });
+});
+
+describe('tagDiff', () => {
+  test('a single-item edit becomes the same two lists a bulk edit sends', () => {
+    expect(tagDiff(['holiday', 'beach'], ['beach', 'greece'])).toEqual({
+      addTags: ['greece'],
+      removeTags: ['holiday'],
+    });
+  });
+
+  test('🔴 re-typing a tag in a different case is not a change', () => {
+    // Otherwise every save mints a second spelling and the chips grow a duplicate of
+    // everything the owner ever re-typed.
+    expect(tagDiff(['Holiday'], ['holiday'])).toEqual({ addTags: [], removeTags: [] });
+  });
+
+  test('an item with no tags at all diffs against the empty list', () => {
+    expect(tagDiff(undefined, ['greece'])).toEqual({ addTags: ['greece'], removeTags: [] });
+  });
+});
+
+describe('isEmptyMetaChange', () => {
+  test('nothing added, nothing removed and no description is nothing to save', () => {
+    expect(isEmptyMetaChange({ addTags: [], removeTags: [] })).toBe(true);
+  });
+
+  test("clearing a description to '' is a change, not an absence", () => {
+    expect(isEmptyMetaChange({ addTags: [], removeTags: [], description: '' })).toBe(false);
+  });
+});
+
+describe('applyMetaChange', () => {
+  test('adds, removes and keeps the rest in order', () => {
+    expect(
+      applyMetaChange(
+        { tags: ['holiday', 'beach'] },
+        { addTags: ['greece'], removeTags: ['beach'] },
+      ),
+    ).toEqual({ tags: ['holiday', 'greece'] });
+  });
+
+  test('🔴 removal matches case-insensitively, so a re-cased tag is not left behind', () => {
+    expect(applyMetaChange({ tags: ['Holiday'] }, { addTags: [], removeTags: ['holiday'] })).toEqual(
+      { tags: [] },
+    );
+  });
+
+  test('🔴 adding a tag the item already has in another case changes nothing', () => {
+    expect(applyMetaChange({ tags: ['Holiday'] }, { addTags: ['holiday'], removeTags: [] })).toEqual(
+      { tags: ['Holiday'] },
+    );
+  });
+
+  test('a change with no description leaves the key off, so a spread cannot clear one', () => {
+    const next = applyMetaChange(
+      { tags: [], description: 'The one with the dog' },
+      { addTags: ['dog'], removeTags: [] },
+    );
+    expect('description' in next).toBe(false);
+    expect({ ...{ description: 'The one with the dog' }, ...next }).toEqual({
+      description: 'The one with the dog',
+      tags: ['dog'],
+    });
+  });
+
+  test("'' clears the description rather than leaving it", () => {
+    expect(
+      applyMetaChange({ tags: [], description: 'old' }, { addTags: [], removeTags: [], description: '' }),
+    ).toEqual({ tags: [], description: '' });
+  });
+});
+
+describe('tagsOn', () => {
+  test('the union across a selection, de-duplicated across items', () => {
+    expect(
+      tagsOn([{ tags: ['holiday', 'beach'] }, { tags: ['Beach', 'greece'] }, {}]),
+    ).toEqual(['holiday', 'beach', 'greece']);
+  });
+});