Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Mood Board — pure record transforms (issue #911).
*
* Storage-agnostic mutation semantics, mirroring the creativeDirector
* projectsLogic split: each function takes a plain board record and returns the
* next record (or throws a ServerError on a validation failure), leaving the
* load/persist to the db module. A board holds a small bounded `items[]` inline
* — image refs (media-key or external URL) or text notes — that feed the Create
* suite. No file backend exists (mood boards are db-primary, local-only), so
* this module has a single consumer (db.js); it stays a separate pure module so
* the transforms are unit-testable without a live database.
*/
import { randomUUID } from 'crypto';
import { ServerError } from '../../lib/errorHandler.js';
import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import { sanitizeSoftDeleteFields } from '../../lib/syncWire.js';
import { localImageFilename, assetBasename } from '../../lib/localImageFilename.js';
import { isVideoItemMediaKey } from '../../lib/moodBoardValidation.js';
import { isStr } from '../../lib/textUtils.js';
// Bound the inline items[] so a single board row's JSONB can't grow without
// limit (a board is loaded/serialized whole on every read/write). Far above any
// realistic hand-curated board. Enforced in addItem (the add route surfaces the
// BOARD_FULL error); the item schema validates a single item, not the count.
export const MAX_ITEMS_PER_BOARD = 500;
function nowIso() {
return new Date().toISOString();
}
// Build a fresh board record from a validated create input. `id`/`now` are
// injected by the caller (db.js) so this stays pure and testable.
export function buildBoardRecord(input, { id, now = nowIso() } = {}) {
return {
id,
name: input.name,
description: input.description ?? '',
items: [],
createdAt: now,
updatedAt: now,
// Soft-delete / LWW tombstone trio (#1564) — boards federate across peers
// via the per-record push pipeline (record kind `moodBoard`, sync category
// `moodBoards`), so a delete is a tombstone the merge keeps an out-of-date
// peer from resurrecting. Mirrors the creativeDirector project record.
deleted: false,
deletedAt: null,
};
}
/**
* Normalize a raw board record into the canonical stored shape for a sync
* round-trip. Returns null for a non-object or a record without a usable id
* (mirrors `sanitizeProjectForSync`'s "drop on the floor" contract so a
* malformed peer payload can't land). The board body (name/description/items)
* passes through verbatim — it is all app-authored data — while the LWW key
* (`updatedAt`) and the soft-delete trio are normalized so the wire/hash shape
* is stable regardless of on-disk key position.
*/
export function sanitizeBoardForSync(raw) {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
if (!isStr(raw.id) || !raw.id) return null;
const createdAt = isStr(raw.createdAt) ? raw.createdAt : new Date().toISOString();
const updatedAt = isStr(raw.updatedAt) ? raw.updatedAt : createdAt;
const { deleted, deletedAt } = sanitizeSoftDeleteFields(raw);
return { ...raw, createdAt, updatedAt, deleted, deletedAt };
}
/**
* LWW merge decision for one incoming board record against the local copy —
* mirrors `mergeProjectRecord` (creativeDirector/projectsLogic.js):
* - remote sanitized here (drop-on-floor on a malformed payload → `next: null`).
* - No local counterpart → insert the remote verbatim (`inserted: true`).
* - Both present → newer `updatedAt` wins (`compareNewerWins`: epoch-ms,
* unparseable-loses, tie → local). Tombstones ride the same path.
* Returns `{ next, inserted, remoteWins, changed }`; `changed` is false when the
* winner is byte-identical to local. The whole record is LWW-overwritten (no
* field-union), so it is hashed in full by `contentHashForRecord`.
*/
export function mergeBoardRecord(local, remoteRaw) {
const remote = sanitizeBoardForSync(remoteRaw);
if (!remote) return { next: null, inserted: false, remoteWins: false, changed: false };
if (!local) return { next: remote, inserted: true, remoteWins: true, changed: true };
const remoteWins = compareNewerWins(remote.updatedAt, local.updatedAt);
const next = remoteWins ? remote : local;
const changed = JSON.stringify(next) !== JSON.stringify(local);
return { next, inserted: false, remoteWins, changed };
}
// Served-asset dir prefix → peer-sync asset-manifest `kind`. A board item's
// `imageUrl` can point at any same-origin app-path image the media UI surfaces:
// gallery renders (`/data/images/`) AND character/canon reference sheets
// (`/data/image-refs/`) — synthetic sources like `canon-sheet:`/`noun:` aren't
// valid media-keys, so PinToMoodBoardMenu pins them as an `imageUrl` only (their
// `previewUrl` is the `/data/image-refs/...` served path). Both dirs are
// federated asset kinds (see directoryForAssetKind in peerSync.js), so both must
// be advertised in the manifest or the receiver stores a board item pointing at
// a missing local file. Mirrors the prefix vocabulary of directoryForAssetKind.
const APP_IMAGE_URL_PREFIXES = Object.freeze([
['/data/images/', 'image'],
['/data/image-refs/', 'image-ref'],
]);
/**
* Resolve a board item's app-path `imageUrl` to `{ kind, filename }` so the
* peer-sync asset pipeline can hash + transfer the bytes via the right dir.
* Returns null for an empty/non-string value, an external URL (`http(s)://…`,
* `data:`, `blob:`), or any absolute path outside the served-asset dirs above —
* the receiver resolves those itself. A bare/relative ref (no leading `/`) is
* treated as a gallery image filename (legacy shape). A media-key reference
* (`image:<ref>`) is handled separately by the manifest builder (it carries the
* bare ref directly); this covers only the `imageUrl` pointer.
*/
export function imageUrlToAppAsset(imageUrl) {
// Gallery images (the `/data/images/` mount or a bare/relative legacy ref) and
// every rejection — empty/non-string, external URL (`http(s)://…`/`data:`/
// `blob:`), and any other absolute path — are exactly the shared resolver's
// contract, so delegate to it instead of re-deriving them here.
const galleryFilename = localImageFilename(imageUrl);
if (galleryFilename) return { kind: 'image', filename: galleryFilename };
// localImageFilename returned null: external/empty (nothing to ship) or a
// non-gallery absolute path. The only served-asset dir it doesn't cover is
// image-refs — resolve that here, sharing the basename primitive.
if (!isStr(imageUrl)) return null;
const url = imageUrl.trim();
for (const [prefix, kind] of APP_IMAGE_URL_PREFIXES) {
if (kind === 'image') continue; // gallery is handled by localImageFilename above
if (url.startsWith(prefix)) {
const filename = assetBasename(url.slice(prefix.length));
return filename ? { kind, filename } : null;
}
}
return null; // some other absolute path → not a served gallery asset
}
/**
* An image item's LOCAL asset as `{ kind: 'image'|'image-ref', filename }` —
* from its `image:<file>` media key or an app-path `imageUrl` — or null for
* text/video items and external pins. The one rule for "which file on this
* install is this pin", for callers that hand board images to a model.
*/
export function boardItemLocalImage(item) {
if (item?.type !== 'image') return null;
if (isStr(item.mediaKey) && item.mediaKey.startsWith('image:')) {
const filename = assetBasename(item.mediaKey.slice('image:'.length));
return filename ? { kind: 'image', filename } : null;
}
return imageUrlToAppAsset(item.imageUrl);
}
// Stored shape of the board's composite style prompt. Absent optionals become
// explicit nulls; `composedAt` is stamped when the writer didn't send one.
// `null` clears the style (the poster render has nothing to pin to).
function normalizeBoardStyle(style, now = nowIso()) {
if (!style) return null;
return {
prompt: style.prompt,
negativePrompt: style.negativePrompt ?? null,
rationale: style.rationale ?? null,
analyzedItemCount: Number.isInteger(style.analyzedItemCount) ? style.analyzedItemCount : 0,
providerId: style.providerId ?? null,
model: style.model ?? null,
composedAt: style.composedAt ?? now,
};
}
// Apply a PATCH to board-level fields (name/description/style/poster). Absent
// keys preserve the original; a present empty string clears description, and
// `null` clears style or the poster filename. `items` is managed only through
// the dedicated item ops below, never a bulk board PATCH.
export function applyBoardPatch(board, patch) {
const next = { ...board };
if (patch.name !== undefined) next.name = patch.name;
if (patch.description !== undefined) next.description = patch.description;
if (patch.style !== undefined) next.style = normalizeBoardStyle(patch.style);
if (patch.posterImageRef !== undefined) next.posterImageRef = patch.posterImageRef ?? null;
if (patch.collageImageRef !== undefined) next.collageImageRef = patch.collageImageRef ?? null;
next.updatedAt = nowIso();
return next;
}
// Normalize a validated item input into the stored item shape. An image item
// carries a `mediaKey` (an indexed `<kind>:<ref>` asset) OR an `imageUrl`
// (external/pinned), never required to have both; a video item (#4188)
// carries a `video:<filename>` mediaKey plus an optional poster-thumbnail
// `imageUrl`; a text item carries `text`. `caption`/`source` are optional on
// all. The route schema guarantees the type-appropriate field is present, so
// this only fills the shared shape.
function normalizeItem(input, { id, now = nowIso() } = {}) {
const hasMedia = input.type === 'image' || input.type === 'video';
return {
id,
type: input.type,
mediaKey: hasMedia ? (input.mediaKey ?? null) : null,
imageUrl: hasMedia ? (input.imageUrl ?? null) : null,
text: input.type === 'text' ? input.text : null,
prompt: hasMedia ? (input.prompt ?? null) : null,
caption: input.caption ?? null,
source: input.source ?? null,
createdAt: now,
};
}
export function addItem(board, itemInput) {
const items = Array.isArray(board.items) ? board.items : [];
// Runs inside the store's row lock: retrying a lost assignment response
// returns the original pin without overwriting its edited prompt/caption.
const existing = itemInput.mediaKey && items.find(item => item.mediaKey === itemInput.mediaKey);
if (existing) return { board, item: existing };
if (items.length >= MAX_ITEMS_PER_BOARD) {
throw new ServerError(`Board is full (max ${MAX_ITEMS_PER_BOARD} items)`, {
status: 400,
code: 'BOARD_FULL',
});
}
const item = normalizeItem(itemInput, { id: `mbi-${randomUUID()}` });
const next = { ...board, items: [...items, item], updatedAt: nowIso() };
return { board: next, item };
}
// Normalize a validated prompt-from-media analysis patch (#4188 Phase 3) into
// the stored shape: absent optional fields become explicit nulls and
// `analyzedAt` is stamped server-side when the client didn't send one, so
// every stored analysis carries a wall clock for the "analyzed N ago"
// affordance. `null` clears a stored analysis.
function normalizeItemAnalysis(analysis, now = nowIso()) {
if (!analysis) return null;
return {
prompt: analysis.prompt,
negativePrompt: analysis.negativePrompt ?? null,
rationale: analysis.rationale ?? null,
providerId: analysis.providerId ?? null,
model: analysis.model ?? null,
analyzedAt: analysis.analyzedAt ?? now,
};
}
// PATCH a single item's editable fields. caption/source apply to any item;
// the body fields are gated to the item's FIXED type (an item's kind can't
// change after creation) so a patch can't make a text item carry an imageUrl
// or an image item carry text — the schema permits every key, the invariant is
// enforced here where the item's type is known. Absent keys preserve; throws
// NOT_FOUND when the item id isn't on the board.
export function updateItem(board, itemId, patch) {
const items = Array.isArray(board.items) ? board.items : [];
const idx = items.findIndex((it) => it && it.id === itemId);
if (idx === -1) {
throw new ServerError('Item not found', { status: 404, code: 'NOT_FOUND' });
}
const current = items[idx];
const updated = { ...current };
const isMediaItem = current.type === 'image' || current.type === 'video';
const editableKeys = isMediaItem
? ['caption', 'source', 'imageUrl', 'mediaKey', 'prompt']
: ['caption', 'source', 'text'];
for (const key of editableKeys) {
if (patch[key] !== undefined) updated[key] = patch[key];
}
// Analysis (#4188 Phase 3) comes from the item's media, so it only applies
// to media items — a patch carrying it for a text item is silently ignored,
// matching how the other type-gated keys behave. Stored normalized (explicit
// nulls + stamped analyzedAt); `null` clears.
if (isMediaItem && patch.analysis !== undefined) {
updated.analysis = normalizeItemAnalysis(patch.analysis);
}
// Reject a patch that would strip the item's required content (the schema
// permits nulls so a partial edit can clear one of two image sources, but the
// MERGED result must stay valid): an image keeps at least one of
// mediaKey/imageUrl; a text item keeps non-empty text.
if (updated.type === 'image' && !updated.mediaKey && !updated.imageUrl) {
throw new ServerError('An image item must keep a mediaKey or imageUrl', { status: 400, code: 'INVALID_ITEM' });
}
if (updated.type === 'video' && !isVideoItemMediaKey(updated.mediaKey)) {
throw new ServerError('A video item must keep a video:<filename> mediaKey', { status: 400, code: 'INVALID_ITEM' });
}
if (updated.type === 'text' && (typeof updated.text !== 'string' || !updated.text.trim())) {
throw new ServerError('A text item must keep non-empty text', { status: 400, code: 'INVALID_ITEM' });
}
const nextItems = [...items];
nextItems[idx] = updated;
const next = { ...board, items: nextItems, updatedAt: nowIso() };
return { board: next, item: updated };
}
// ─── Text note → image render (#10531) ───────────────────────────────────────
// A text note can be rendered into an image. While the job runs the note carries
// `render: { status, jobId, error, queuedAt }`; when it completes the note turns
// into an image item in place (same id and position) — the one sanctioned type
// change, since the render IS the note's visual form.
function findItemIndex(board, itemId) {
const items = Array.isArray(board.items) ? board.items : [];
const idx = items.findIndex((it) => it && it.id === itemId);
if (idx === -1) throw new ServerError('Item not found', { status: 404, code: 'NOT_FOUND' });
return { items, idx };
}
function replaceItem(board, items, idx, item) {
const nextItems = [...items];
nextItems[idx] = item;
return { ...board, items: nextItems, updatedAt: nowIso() };
}
// Mark a text note queued before its job is enqueued, so a second click (or an
// autopilot retry) can't queue a duplicate. `isLive(jobId)` says whether an
// earlier render's job is still queued/running; a dead one may be replaced. A
// claim that never got its job id (the process died mid-enqueue) expires.
const RENDER_CLAIM_TTL_MS = 10 * 60 * 1000;
const INTERRUPTED_RENDER_ERROR = 'interrupted by restart';
// A restart archives the media job without telling the note, and replaying that
// failure at boot would run every other terminal listener. Project the same
// outcome when the board is read: a queued note whose job is gone fails, and a
// claim that never received a job id keeps the claim TTL above. `updatedAt`
// is wall-clock so the healed record wins LWW; `now` is only the TTL clock.
export function projectInterruptedNoteRenders(board, { isLive = () => false, now = nowIso() } = {}) {
if (!board || !Array.isArray(board.items)) return { board, changed: false };
let changed = false;
const items = board.items.map((item) => {
const render = item?.render;
if (!item || item.type !== 'text' || render?.status !== 'queued') return item;
const live = render.jobId
? Boolean(isLive(render.jobId))
: Date.parse(now) - Date.parse(render.queuedAt) < RENDER_CLAIM_TTL_MS;
if (live) return item;
changed = true;
return { ...item, render: { ...render, status: 'failed', error: INTERRUPTED_RENDER_ERROR } };
});
if (!changed) return { board, changed: false };
return { board: { ...board, items, updatedAt: nowIso() }, changed: true };
}
export function claimItemRender(board, itemId, { isLive = () => false, now = nowIso(), options } = {}) {
const { items, idx } = findItemIndex(board, itemId);
const current = items[idx];
if (current.type !== 'text') {
throw new ServerError('Only a text note can be rendered', { status: 409, code: 'MOOD_BOARD_ITEM_NOT_TEXT' });
}
const render = current.render;
const pending = render?.status === 'queued' && (render.jobId
? isLive(render.jobId)
: Date.parse(now) - Date.parse(render.queuedAt) < RENDER_CLAIM_TTL_MS);
if (pending) {
throw new ServerError('This note is already rendering', { status: 409, code: 'MOOD_BOARD_RENDER_BUSY' });
}
const item = { ...current, render: { status: 'queued', jobId: null, error: null, queuedAt: now, ...(options ? { options } : {}) } };
return { board: replaceItem(board, items, idx, item), item };
}
// Record the queued job id, or a failure. Applies only while the note is still
// the text item this render claimed: a job that already finished (the note is
// now an image) or a newer claim (a different jobId) leaves the board untouched.
export function settleItemRender(board, itemId, { jobId, status, error = null }) {
const { items, idx } = findItemIndex(board, itemId);
const current = items[idx];
const render = current.render;
if (current.type !== 'text' || !render || (render.jobId && render.jobId !== jobId)) {
return { board, item: current, changed: false };
}
const item = { ...current, render: { ...render, jobId: jobId ?? render.jobId, status, error } };
return { board: replaceItem(board, items, idx, item), item, changed: true };
}
// Turn the rendered note into an image item. The note text becomes the caption
// (the schema's caption bound) and the submitted prompt the item prompt, so the
// board's analyze step skips it. Skips a stale job, as settleItemRender does.
export function applyRenderedItem(board, itemId, { jobId, filename, prompt }) {
const { items, idx } = findItemIndex(board, itemId);
const current = items[idx];
const render = current.render;
if (current.type !== 'text' || !render || (render.jobId && render.jobId !== jobId)) {
return { board, item: current, changed: false };
}
const item = {
id: current.id,
type: 'image',
mediaKey: `image:${filename}`,
imageUrl: null,
text: null,
prompt: isStr(prompt) && prompt.trim() ? prompt.trim().slice(0, 8000) : null,
caption: current.text.slice(0, 2000),
source: current.source ?? null,
createdAt: current.createdAt,
renderedAt: nowIso(),
};
return { board: replaceItem(board, items, idx, item), item, changed: true };
}
// Remove an item by id. Returns `removed: false` (no write) when the id is
// absent so the db layer can skip a wasted row rewrite.
export function removeItem(board, itemId) {
const items = Array.isArray(board.items) ? board.items : [];
const nextItems = items.filter((it) => !(it && it.id === itemId));
if (nextItems.length === items.length) {
return { board, removed: false };
}
const next = { ...board, items: nextItems, updatedAt: nowIso() };
return { board: next, removed: true };
}
// Faithful conflict-restore of the restorable board fields (RESTORABLE_FIELDS.
// moodBoard = name/description/items/style/posterImageRef). Unlike applyBoardPatch
// — the route PATCH path, which does not touch items because they are managed
// through the dedicated item ops — a "restore my whole version" must bring back
// the board's items[], and the composite style + poster when the journaled
// version had them. The conflict resolver narrows `patch` to the allowed fields
// (via `pick`), so this just spreads the present ones and bumps updatedAt so the
// restore wins LWW and re-propagates. Mirrors creativeDirector's
// applyProjectPatch wholesale-spread restore path.
export function applyBoardRestore(board, patch) {
const next = { ...board };
if (patch.name !== undefined) next.name = patch.name;
if (patch.description !== undefined) next.description = patch.description;
if (Array.isArray(patch.items)) next.items = patch.items;
if (patch.style !== undefined) next.style = normalizeBoardStyle(patch.style);
if (patch.posterImageRef !== undefined) next.posterImageRef = patch.posterImageRef ?? null;
if (patch.collageImageRef !== undefined) next.collageImageRef = patch.collageImageRef ?? null;
next.updatedAt = nowIso();
return next;
}
// ─── Pinterest board link (mood-board importer) ──────────────────────────────
// A board can be linked to a public Pinterest board's RSS feed. The link is an
// additive `pinterest` sub-object on the board record — it rides through
// sanitizeBoardForSync's `...raw` spread, so it federates with the board (no
// schema-version bump: full-record LWW, and an older peer preserves the unknown
// key). `lastSyncedAt` tracks the most recent manual "Sync now".
// Set (or replace) the Pinterest link. Preserve the prior sync timestamp only
// when re-linking the SAME feed; pointing the board at a DIFFERENT Pinterest
// board clears lastSyncedAt, otherwise the UI would claim the new board was
// "last synced" at the old board's time before any sync has run.
export function applyPinterestLink(board, { feedUrl, boardUrl }) {
const prior = board.pinterest || {};
const sameFeed = prior.feedUrl === feedUrl;
return {
...board,
pinterest: {
feedUrl,
boardUrl: boardUrl ?? null,
lastSyncedAt: sameFeed ? (prior.lastSyncedAt ?? null) : null,
},
updatedAt: nowIso(),
};
}
// Self-heal a stale Pinterest feed (e.g. a section URL saved before section
// detection, whose `/user/board/section.rss` feed Pinterest serves as HTML) to a
// corrected `feedUrl`, but ONLY when the board's currently-persisted feed still
// matches `fromFeedUrl` — the feed read at sync start. This guards the same
// single-user re-entrancy race as appendPinterestPins: the sync's getBoard()
// runs before this locked write, so the user can unlink or repoint the board in
// between. Without the guard, applyPinterestLink would unconditionally rewrite
// the link and resurrect/clobber the user's newer state. Returns changed:false
// (no write) when the board was unlinked/repointed concurrently or is already
// on the corrected feed. Returns { board, changed }.
export function healPinterestFeedRecord(board, { fromFeedUrl, feedUrl, boardUrl }) {
if (board.pinterest?.feedUrl !== fromFeedUrl || fromFeedUrl === feedUrl) {
return { board, changed: false };
}
return { board: applyPinterestLink(board, { feedUrl, boardUrl }), changed: true };
}
// Remove the Pinterest link. Returns changed:false (no write) when the board
// wasn't linked, so the db layer can skip a wasted row rewrite + peer push.
export function clearPinterestLinkRecord(board) {
if (!board.pinterest) return { board, changed: false };
const next = { ...board };
delete next.pinterest;
next.updatedAt = nowIso();
return { board: next, changed: true };
}
/**
* Shared dedupe-by-`source` + MAX_ITEMS_PER_BOARD-capacity core for every
* "append already-downloaded media as board items" flow (the persisted
* Pinterest sync below and the one-shot X post importer) — one place owning
* the truncate-rather-than-throw contract so it can't drift between the two
* callers. `buildItem(imp)` turns one `imported` entry into a normalized item;
* the caller decides the rest (what to stamp on the board afterward).
*/
function buildFreshItems(existingItems, imported, buildItem) {
const seen = new Set(existingItems.map((it) => it && it.source).filter(Boolean));
const capacity = Math.max(0, MAX_ITEMS_PER_BOARD - existingItems.length);
const fresh = [];
for (const imp of Array.isArray(imported) ? imported : []) {
if (fresh.length >= capacity) break;
if (imp.source && seen.has(imp.source)) continue;
if (imp.source) seen.add(imp.source);
fresh.push(buildItem(imp));
}
return fresh;
}
/**
* Append already-downloaded Pinterest pins as image items, then stamp the sync
* timestamp. Each `imported` entry is `{ imageUrl, caption, source }` where
* `source` is the pin permalink — the dedupe key (see buildFreshItems). Always
* re-stamps `pinterest.lastSyncedAt` (even on zero new) so the UI reflects the
* check. Returns `{ board, added, aborted }`.
*
* `expectedFeedUrl` guards a single-user re-entrancy race: the feed fetch +
* image downloads run OUTSIDE the row lock, so the user can unlink or re-link
* the board mid-sync. When the persisted feed no longer matches the one this
* sync fetched, abort — append no pins and DON'T stamp lastSyncedAt — so stale
* pins never land on a board that was unlinked/repointed.
*/
export function appendPinterestPins(board, imported, { syncedAt = nowIso(), expectedFeedUrl = null } = {}) {
if (expectedFeedUrl && board.pinterest?.feedUrl !== expectedFeedUrl) {
return { board, added: 0, aborted: true };
}
const items = Array.isArray(board.items) ? board.items : [];
const fresh = buildFreshItems(items, imported, (imp) => normalizeItem(
{ type: 'image', imageUrl: imp.imageUrl, caption: imp.caption ?? null, source: imp.source ?? null },
{ id: `mbi-${randomUUID()}`, now: syncedAt },
));
const next = {
...board,
items: [...items, ...fresh],
pinterest: { ...(board.pinterest || {}), lastSyncedAt: syncedAt },
updatedAt: nowIso(),
};
return { board: next, added: fresh.length, aborted: false };
}
// ─── One-shot media imports (X post importer) ────────────────────────────────
/**
* Append already-downloaded media items in ONE locked write — same
* dedupe/capacity core as appendPinterestPins (buildFreshItems), generalized
* for a one-shot import (X post) that has no persisted link/lastSyncedAt to
* stamp. Each `imported` entry is `{ type, imageUrl, mediaKey, caption,
* source }`; `source` is the dedupe key, re-checked here as an in-lock safety
* net (the service pre-dedupes before downloading, but two concurrent imports
* of the same post could race between that check and this write). Returns
* `{ board, added }`.
*/
export function appendImportedItems(board, imported) {
const items = Array.isArray(board.items) ? board.items : [];
const fresh = buildFreshItems(items, imported, (imp) => normalizeItem(
{ type: imp.type, imageUrl: imp.imageUrl ?? null, mediaKey: imp.mediaKey ?? null, caption: imp.caption ?? null, source: imp.source ?? null },
{ id: `mbi-${randomUUID()}` },
));
const next = { ...board, items: [...items, ...fresh], updatedAt: nowIso() };
return { board: next, added: fresh.length };
}
// ─── Re-hosting external media ───────────────────────────────────────────────
/** True for an http(s) URL — the only `imageUrl` shape that isn't a local asset. */
export function isExternalImageUrl(url) {
return isStr(url) && /^https?:\/\//i.test(url.trim());
}
/** Media items whose displayed image still points at a remote host. */
export function externalImageItems(board) {
const items = Array.isArray(board?.items) ? board.items : [];
return items.filter((it) => it && (it.type === 'image' || it.type === 'video') && isExternalImageUrl(it.imageUrl));
}
/**
* Swap re-hosted images in. Each replacement is `{ id, from, to }`; it only
* applies while the item still carries the `from` URL the download was started
* for (the fetch runs outside the row lock, so the user may have edited the item
* meanwhile). Returns `{ board, changed }`.
*/
export function applyLocalizedImageUrls(board, replacements) {
const items = Array.isArray(board.items) ? board.items : [];
const byId = new Map((replacements || []).map((r) => [r.id, r]));
let changed = 0;
const nextItems = items.map((it) => {
const r = it && byId.get(it.id);
if (!r || it.imageUrl !== r.from) return it;
changed += 1;
return { ...it, imageUrl: r.to };
});
if (!changed) return { board, changed: 0 };
return { board: { ...board, items: nextItems, updatedAt: nowIso() }, changed };
}
// ─── Collage geometry ────────────────────────────────────────────────────────
/**
* Grid dimensions that keep the composite as square as possible: the smallest
* column count whose square covers `count`, then only as many rows as needed
* (e.g. 5 → 3×2, 10 → 4×3, 16 → 4×4). Cells are square, so the image aspect
* follows the grid aspect.
*/
export function squareGridDims(count) {
const n = Math.max(1, Math.floor(count) || 1);
const cols = Math.ceil(Math.sqrt(n));
return { cols, rows: Math.ceil(n / cols) };
}
/** Evenly spaced sample times — the midpoint of each of `count` equal segments. */
export function frameSampleTimes(durationSec, count) {
return Array.from({ length: count }, (_, i) => ((i + 0.5) * durationSec) / count);
}