auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/project-folders.ts

@@ -0,0 +1,144 @@
+/**
+ * Folders of the Projects popover: a way to group the list, kept by Studio beside the list itself (nothing moves on
+ * disk). A project is in at most one (`folderId`); the top level shows the projects in none.
+ *
+ *   GET / POST { name } /api/projects/folders → { folders } / { folder }
+ *   PATCH { name } /api/projects/folders/:id → { folder }; DELETE /api/projects/folders/:id → { projects } (their ids)
+ *   PUT { folderId } /api/projects/:id/folder (null: no folder)
+ */
+
+/** `parentId`: the folder it is in (none, or one that is gone: the top level). */
+export type ProjectFolder = { id: string; name: string; createdAt: number; parentId?: string };
+
+/** What of a project the list sorts, files and searches by. */
+export type ListedProject = {
+  id: string;
+  name: string;
+  openedAt: number;
+  createdAt?: number;
+  /** the film's length in seconds, when known */
+  duration?: number;
+  folderId?: string;
+  poster?: string;
+};
+
+export type LibrarySort = 'recent' | 'newest' | 'oldest' | 'duration' | 'title';
+
+async function call<T>(path: string, method = 'GET', json?: unknown): Promise<T> {
+  const res = await fetch(`/api/projects/${path}`, {
+    method,
+    ...(json === undefined ? {} : { headers: { 'content-type': 'application/json' }, body: JSON.stringify(json) }),
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(String(body.error ?? `Studio answered ${res.status}`));
+  return body as T;
+}
+
+export const folderApi = {
+  list: () => call<{ folders: ProjectFolder[] }>('folders').then((r) => r.folders),
+  create: (name: string, parentId: string | null = null) => call<{ folder: ProjectFolder }>('folders', 'POST', { name, ...(parentId ? { parentId } : {}) }).then((r) => r.folder),
+  rename: (id: string, name: string) => call<{ folder: ProjectFolder }>(`folders/${encodeURIComponent(id)}`, 'PATCH', { name }).then((r) => r.folder),
+  /** takes the folder off the list; resolves to the ids of the projects that were in it */
+  remove: (id: string) => call<{ projects: string[] }>(`folders/${encodeURIComponent(id)}`, 'DELETE').then((r) => r.projects),
+  move: (projectId: string, folderId: string | null) => call<object>(`${encodeURIComponent(projectId)}/folder`, 'PUT', { folderId }),
+  /** a folder into another (null: the top level), with what it holds */
+  moveFolder: (id: string, parentId: string | null) => call<{ folder: ProjectFolder }>(`folders/${encodeURIComponent(id)}`, 'PATCH', { parentId }).then((r) => r.folder),
+};
+
+/**
+ * What the list starts with: "New project" wherever projects are listed, the top level or a folder (not over a
+ * search's results); the examples at the top level only.
+ */
+export function listStarts({ folderId, query }: { folderId: string | null; query: string }): { newProject: boolean; examples: boolean } {
+  const listing = !query.trim();
+  return { newProject: listing, examples: listing && folderId === null };
+}
+
+/**
+ * A new project inside `folderId` (null: the top level): made, then filed there before it opens. One that cannot be
+ * filed (its folder went meanwhile) is still made, at the top level.
+ */
+export async function newProjectIn<P extends { id: string }>(
+  folderId: string | null,
+  { create, move }: { create: () => Promise<P>; move: (projectId: string, folderId: string | null) => Promise<unknown> },
+): Promise<P> {
+  const project = await create();
+  if (folderId) await move(project.id, folderId).catch(() => {});
+  return project;
+}
+
+/**
+ * The projects to show, sorted. Like a file system: the top level shows the projects in no folder, a folder its own.
+ * A search looks everywhere (a person searching wants "where is that film", not to guess its folder first).
+ */
+export function visibleProjects<P extends ListedProject>(
+  projects: readonly P[],
+  { query, folderId, sort, titleOf, folders }: {
+    query: string;
+    folderId: string | null;
+    sort: LibrarySort;
+    titleOf: (project: P) => string;
+    /** the folders there are: a project filed in one that is gone shows at the top level */
+    folders: readonly ProjectFolder[];
+  },
+): P[] {
+  const needle = query.trim().toLocaleLowerCase();
+  const known = new Set(folders.map((f) => f.id));
+  const placed = (p: P) => (p.folderId && known.has(p.folderId) ? p.folderId : null);
+  const created = (p: P) => p.createdAt ?? p.openedAt;
+  return projects
+    .filter((p) => (needle ? p.name.toLocaleLowerCase().includes(needle) : placed(p) === folderId))
+    .sort((a, b) => {
+      if (sort === 'recent') return b.openedAt - a.openedAt;
+      if (sort === 'oldest') return created(a) - created(b);
+      if (sort === 'duration') return (b.duration ?? 0) - (a.duration ?? 0);
+      if (sort === 'title') return titleOf(a).localeCompare(titleOf(b));
+      return created(b) - created(a);
+    });
+}
+
+/** The folder a folder is in, or null (the top level, or its parent is gone). */
+export function parentOf(folder: ProjectFolder, folders: readonly ProjectFolder[]): string | null {
+  return folder.parentId && folders.some((f) => f.id === folder.parentId) ? folder.parentId : null;
+}
+
+/** A folder and the folders it is in, the outermost first (the breadcrumb). A loop is cut where it comes back. */
+export function folderTrail(folders: readonly ProjectFolder[], id: string | null): ProjectFolder[] {
+  const trail: ProjectFolder[] = [];
+  const seen = new Set<string>();
+  for (let at = folders.find((f) => f.id === id); at && !seen.has(at.id); at = folders.find((f) => f.id === parentOf(at!, folders))) {
+    seen.add(at.id);
+    trail.unshift(at);
+  }
+  return trail;
+}
+
+/** The folders that hold `id`, itself first: a project in it counts for each of them. */
+const holders = (folders: readonly ProjectFolder[], id: string) => folderTrail(folders, id).map((f) => f.id).reverse();
+
+/** How many projects each folder holds, those of the folders inside it too. */
+export function folderCounts(projects: readonly ListedProject[], folders: readonly ProjectFolder[] = []): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const p of projects) {
+    if (!p.folderId) continue;
+    for (const id of folders.length ? holders(folders, p.folderId) : [p.folderId]) counts[id] = (counts[id] ?? 0) + 1;
+  }
+  return counts;
+}
+
+/**
+ * The small covers on each folder's card: its newest projects, up to four, each with its poster when it has one (a
+ * cover without one shows that project's own face, as its card does).
+ */
+export function folderPosters(projects: readonly ListedProject[], folders: readonly ProjectFolder[] = []): Record<string, { id: string; poster?: string }[]> {
+  const out: Record<string, { id: string; poster?: string }[]> = {};
+  const newest = [...projects].sort((a, b) => (b.createdAt ?? b.openedAt) - (a.createdAt ?? a.openedAt));
+  for (const p of newest) {
+    if (!p.folderId) continue;
+    for (const id of folders.length ? holders(folders, p.folderId) : [p.folderId]) {
+      const list = (out[id] ??= []);
+      if (list.length < 4) list.push(p.poster ? { id: p.id, poster: p.poster } : { id: p.id });
+    }
+  }
+  return out;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/project-history.ts

@@ -0,0 +1,188 @@
+/**
+ * A project's version history as the Version history panel shows it, and the calls that change it
+ * (studio/server/history.mjs): git, as a person knows it from GitHub — commits on branches, uncommitted changes,
+ * switching, merging — told in the film's terms. Every commit is the person's; nothing commits on its own.
+ *
+ *   GET    /api/projects/:id/history                       → { status, commits }
+ *   GET    /api/projects/:id/history/files                 → { held, ignored }: the film's files, and the others
+ *   GET    /api/projects/:id/history/poster/:commit        the film's picture when it was committed
+ *   POST   /api/projects/:id/history/commit   { message }
+ *   POST   /api/projects/:id/history/discard
+ *   POST   /api/projects/:id/history/restore  { commit }   the commit's files, as uncommitted changes
+ *   POST   /api/projects/:id/history/checkout { branch, create?, from?, carry? }
+ *   PATCH  /api/projects/:id/history/branches/:name { name }
+ *   DELETE /api/projects/:id/history/branches/:name[?force=1]
+ *   POST   /api/projects/:id/history/merge    { branch, message, prefer? }
+ *
+ * While an action runs, the project's events say how far it is ({ type: 'history-progress' }: HistoryProgress).
+ * A refusal comes with a `code` ('dirty', 'nothing', 'conflict', 'unmerged', 'exists', 'name', 'current', 'none'),
+ * which the panel says in its own words.
+ */
+
+export interface Counts { added: number; removed: number; edited: number }
+/** What changed, as the film tells it (see history.mjs Summary). */
+export interface Summary { scenes: Counts; sounds: Counts; stage: boolean; other: boolean }
+export interface Branch { name: string; commit: string; at: number; message: string; current: boolean; parked: boolean }
+/** The film's files now (what a commit keeps), and how many other files the folder has (never kept). */
+export interface HistoryFiles { held: number; heldBytes: number; ignored: number }
+export interface HistoryStatus {
+  branch: string;
+  head: string | null;
+  branches: Branch[];
+  changes: { count: number; summary: Summary } | null;
+  files: HistoryFiles | null;
+}
+/** A file, by its path in the project, and its size. */
+export interface HistoryFile { path: string; size: number }
+/** How far an action is: `phase` reading the film's files, keeping media, writing files, or updating the history. */
+export interface HistoryProgress { op: string; phase: 'scan' | 'store' | 'write' | 'migrate'; done: number; total: number }
+export interface Commit { commit: string; parents: string[]; at: number; message: string; body: string; tags: string[]; summary: Summary }
+export interface HistoryState { status: HistoryStatus; commits: Commit[] }
+
+const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const counts = (raw: unknown): Counts => {
+  const c = (raw ?? {}) as Record<string, unknown>;
+  return { added: num(c.added), removed: num(c.removed), edited: num(c.edited) };
+};
+const summaryOf = (raw: unknown): Summary => {
+  const s = (raw ?? {}) as Record<string, unknown>;
+  return { scenes: counts(s.scenes), sounds: counts(s.sounds), stage: s.stage === true, other: s.other === true };
+};
+const text = (v: unknown) => (typeof v === 'string' ? v : '');
+
+/** The server's answer, checked: anything unreadable is dropped rather than drawn as an empty row. */
+export function normalizeHistory(raw: unknown): HistoryState | null {
+  const body = raw as { status?: Record<string, unknown>; commits?: unknown } | null;
+  const s = body?.status;
+  if (!s || typeof s.branch !== 'string') return null;
+  const branches: Branch[] = (Array.isArray(s.branches) ? s.branches : []).flatMap((b) => {
+    const r = b as Record<string, unknown> | null;
+    return r && typeof r.name === 'string' && r.name
+      ? [{ name: r.name, commit: text(r.commit), at: num(r.at), message: text(r.message), current: r.current === true, parked: r.parked === true }]
+      : [];
+  });
+  const changes = s.changes && typeof s.changes === 'object'
+    ? { count: num((s.changes as Record<string, unknown>).count), summary: summaryOf((s.changes as Record<string, unknown>).summary) }
+    : null;
+  const commits: Commit[] = (Array.isArray(body.commits) ? body.commits : []).flatMap((c) => {
+    const r = c as Record<string, unknown> | null;
+    if (!r || typeof r.commit !== 'string' || !r.commit) return [];
+    return [{
+      commit: r.commit,
+      parents: Array.isArray(r.parents) ? r.parents.filter((p): p is string => typeof p === 'string') : [],
+      at: num(r.at), message: text(r.message), body: text(r.body),
+      tags: Array.isArray(r.tags) ? r.tags.filter((t): t is string => typeof t === 'string' && !!t) : [],
+      summary: summaryOf(r.summary),
+    }];
+  });
+  const f = s.files as Record<string, unknown> | null | undefined;
+  const files = f && typeof f === 'object' ? { held: num(f.held), heldBytes: num(f.heldBytes), ignored: num(f.ignored) } : null;
+  return { status: { branch: s.branch, head: typeof s.head === 'string' ? s.head : null, branches, changes, files }, commits };
+}
+
+/**
+ * What changed, as the parts of a sentence, in the order a person reads them: scenes before sounds, added before
+ * edited before removed. Each is a string key and its count (the sentence is the strings' job). Nothing that a scene
+ * or a sound tells: 'look' (the picture's size, or a file the scenes share) when that changed, else 'same'.
+ */
+export function summaryParts(summary: Summary): Array<{ key: string; n: number }> {
+  const parts: Array<{ key: string; n: number }> = [];
+  for (const [what, c] of [['scenes', summary.scenes], ['sounds', summary.sounds]] as const) {
+    if (c.added) parts.push({ key: `${what}Added`, n: c.added });
+    if (c.edited) parts.push({ key: `${what}Edited`, n: c.edited });
+    if (c.removed) parts.push({ key: `${what}Removed`, n: c.removed });
+  }
+  if (!parts.length) parts.push({ key: summary.stage || summary.other ? 'look' : 'same', n: 0 });
+  return parts;
+}
+
+export type HistoryAge =
+  | { unit: 'now' }
+  | { unit: 'minute' | 'hour' | 'day'; n: number };
+
+/**
+ * How long ago, as a unit and a number (the sentence is the strings' job). An unreadable time gives null: no time is
+ * better than "NaN minutes ago". A clock slightly ahead gives a future time; that counts as just now.
+ */
+export function historyAge(at: number, now: number): HistoryAge | null {
+  if (!Number.isFinite(at) || at <= 0) return null;
+  const minutes = Math.floor((now - at) / 60_000);
+  if (minutes < 1) return { unit: 'now' };
+  if (minutes < 60) return { unit: 'minute', n: minutes };
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return { unit: 'hour', n: hours };
+  return { unit: 'day', n: Math.floor(hours / 24) };
+}
+
+/** A history call's outcome: done (with what came back), or refused with the server's `code`. */
+export type HistoryResult<T = Record<string, unknown>> = { ok: true; body: T } | { ok: false; status: number; code: string | null; commits?: number };
+
+async function call<T = Record<string, unknown>>(projectId: string, path: string, method = 'GET', json?: unknown): Promise<HistoryResult<T>> {
+  try {
+    const res = await fetch(`/api/projects/${encodeURIComponent(projectId)}/history${path}`, {
+      method,
+      ...(json === undefined ? {} : { headers: { 'content-type': 'application/json' }, body: JSON.stringify(json) }),
+    });
+    const body = await res.json().catch(() => ({})) as Record<string, unknown>;
+    if (res.ok) return { ok: true, body: body as T };
+    return { ok: false, status: res.status, code: typeof body.code === 'string' ? body.code : null, ...(typeof body.commits === 'number' ? { commits: body.commits } : {}) };
+  } catch {
+    return { ok: false, status: 503, code: null };
+  }
+}
+
+const fileList = (raw: unknown): HistoryFile[] => (Array.isArray(raw) ? raw : []).flatMap((f) => {
+  const r = f as Record<string, unknown> | null;
+  return r && typeof r.path === 'string' ? [{ path: r.path, size: num(r.size) }] : [];
+});
+
+export const historyApi = {
+  load: async (id: string) => {
+    const r = await call(id, '');
+    return r.ok ? normalizeHistory(r.body) : null;
+  },
+  files: async (id: string): Promise<{ held: HistoryFile[]; ignored: HistoryFile[] } | null> => {
+    const r = await call(id, '/files');
+    return r.ok ? { held: fileList(r.body.held), ignored: fileList(r.body.ignored) } : null;
+  },
+  commit: (id: string, message: string) => call(id, '/commit', 'POST', { message }),
+  discard: (id: string) => call(id, '/discard', 'POST', {}),
+  restore: (id: string, commit: string) => call(id, '/restore', 'POST', { commit }),
+  checkout: (id: string, o: { branch: string; create?: boolean; from?: string; carry?: 'leave' | 'bring' }) =>
+    call<{ parkedBack?: boolean }>(id, '/checkout', 'POST', o),
+  rename: (id: string, from: string, name: string) => call(id, `/branches/${encodeURIComponent(from)}`, 'PATCH', { name }),
+  remove: (id: string, name: string, force = false) => call(id, `/branches/${encodeURIComponent(name)}${force ? '?force=1' : ''}`, 'DELETE'),
+  merge: (id: string, o: { branch: string; message: string; prefer?: 'ours' | 'theirs' }) => call<{ merged?: boolean }>(id, '/merge', 'POST', o),
+};
+
+/** The picture of a commit (taken when it was committed). */
+export const commitPoster = (projectId: string, commit: string) =>
+  `/api/projects/${encodeURIComponent(projectId)}/history/poster/${commit}`;
+
+/**
+ * Which sentence a refusal gets: always our own words, never the server's text. Codes the panel handles with a
+ * question of its own ('dirty' before going back, 'conflict' on a merge, 'unmerged' on a delete) are asked, not said.
+ */
+export function historyErrorKey(result: { status: number; code: string | null }): string {
+  switch (result.code) {
+    case 'dirty': return 'versions.errorDirty';
+    case 'nothing': return 'versions.errorNothing';
+    case 'conflict': return 'versions.errorCarry';
+    case 'exists': return 'versions.errorExists';
+    case 'name': return 'versions.errorName';
+    case 'message': return 'versions.errorMessage';
+    case 'current': return 'versions.errorCurrent';
+    default: break;
+  }
+  if (result.status === 404 || result.status === 501 || result.status === 503) return 'versions.errorUnavailable';
+  return 'versions.errorGeneric';
+}
+
+/** A progress event's numbers, checked: null when it is not one. */
+export function historyProgressOf(raw: unknown): HistoryProgress | null {
+  const r = raw as Record<string, unknown> | null;
+  if (!r || r.type !== 'history-progress') return null;
+  const phase = r.phase === 'scan' || r.phase === 'store' || r.phase === 'write' || r.phase === 'migrate' ? r.phase : null;
+  if (!phase) return null;
+  return { op: text(r.op), phase, done: num(r.done), total: num(r.total) };
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/project-sources.ts

@@ -0,0 +1,283 @@
+/**
+ * Starting from an existing film, on the Projects page: a folder opened (the web editor's own folder browser, or the
+ * app's native dialog), a film got from GitHub, an example, and a moved project located again. The calls and what
+ * the dialogs work out from their answers (studio/server/browse.mjs, fetch-repo.mjs, examples.mjs).
+ *
+ *   GET  /api/browse?path=          → a folder's folders (only under the home folder), and places to start
+ *   POST /api/projects { path, create: false } → { project }, or 409 code 'no-film' (ask before starting one there)
+ *   POST /api/projects/fetch { url } → { job }; GET / DELETE /api/projects/fetch/:id
+ *   GET  /api/examples              → { examples } (none when the index cannot be read)
+ *   GET  /api/skills?project=<id>   → { skills } (the project's, the person's own, the official ones)
+ *   POST /api/projects/:id/locate { path } → { project }
+ */
+
+export type BrowseFolder = { name: string; path: string; film: boolean };
+export type BrowseListing = {
+  path: string;
+  root: string;
+  parent: string | null;
+  name: string;
+  film: boolean;
+  folders: BrowseFolder[];
+  more: boolean;
+  places: { id: string; path: string }[];
+  recent: string[];
+};
+export type FetchPhase = 'lookup' | 'download' | 'checkout' | 'copy';
+export type FetchJob = {
+  id: string;
+  url: string;
+  label: string;
+  state: 'running' | 'done' | 'failed';
+  phase: FetchPhase;
+  percent: number | null;
+  bytes: number;
+  /** the size of the whole, when it is known before it downloads (GitHub over https); null through git */
+  total: number | null;
+  error?: string;
+  code?: string;
+  project?: { id: string };
+};
+/** a skill a project can be made with (openfilm/src/skills.mjs): the project's own, the person's, or official */
+export type SkillEntry = {
+  name: string; description: string; source: 'project' | 'mine' | 'official'; scripts: number;
+  /** how people see it (its openfilm.json): a title and a one-line summary, by language */
+  shown?: { title: Record<string, string>; summary: Record<string, string>; details?: Record<string, string> };
+  /** its openfilm.json's (else its front matter's) */
+  version?: string;
+  /** a way of working (a kind of job) or a look; its place among its kind; its mark */
+  kind?: 'workflow' | 'style'; order?: number; icon?: string;
+  /** addresses of its cover picture and preview video, when it has them */
+  cover?: string; preview?: string;
+  /** where its source can be read (a repository's address) */
+  repository?: string;
+  /** the person's own: where it came from (a link, a folder), or made where it is */
+  origin?: { from: 'link' | 'folder'; address: string } | { from: 'made' };
+  /** an official one: installed to be used (the person's own and a project's are installed already) */
+  installed?: boolean;
+  /** turned off: offered to no agent until it is turned on again */
+  off?: true;
+};
+/** an example film's part, as its index names it (`S2-Hook`), from and to in seconds */
+export type ExampleSegment = { title: string; from: number; to: number };
+export type Example = {
+  id: string; title: string; description: string; poster: string | null; video: string | null; duration: number | null; url: string;
+  category: string | null; segments: ExampleSegment[];
+};
+
+export class SourceError extends Error {
+  readonly status: number;
+  readonly code: string | null;
+  constructor(message: string, status: number, code: string | null) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+async function call<T>(path: string, method = 'GET', json?: unknown): Promise<T> {
+  const res = await fetch(`/api/${path}`, {
+    method,
+    ...(json === undefined ? {} : { headers: { 'content-type': 'application/json' }, body: JSON.stringify(json) }),
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new SourceError(String(body.error ?? `Studio answered ${res.status}`), res.status, typeof body.code === 'string' ? body.code : null);
+  return body as T;
+}
+
+/* what the galleries read last: shown at once when one opens, and asked for again behind it */
+const seen: { examples: Example[] | null; skills: Map<string, SkillEntry[]> } = { examples: null, skills: new Map() };
+/** The examples read last, or null. */
+export const seenExamples = (): Example[] | null => seen.examples;
+/** The skills read last for a project (else for no project: the official ones and the person's own), or null. */
+export const seenSkills = (projectId?: string | null): SkillEntry[] | null => seen.skills.get(projectId ?? '') ?? seen.skills.get('') ?? null;
+
+/** The desktop's add dialog and Studio's gallery share the window. */
+export const SKILLS_CHANGED = 'openfilm:skills-changed';
+
+/** Read an open gallery's skills again after an addition; a stale request must not replace the newer list. */
+export function watchSkills(projectId: string | null | undefined, changed: (skills: SkillEntry[]) => void, events: EventTarget = window): () => void {
+  let revision = 0;
+  const refresh = () => {
+    const request = ++revision;
+    void sourcesApi.skills(projectId).then((skills) => { if (request === revision) changed(skills); });
+  };
+  events.addEventListener(SKILLS_CHANGED, refresh);
+  refresh();
+  return () => { ++revision; events.removeEventListener(SKILLS_CHANGED, refresh); };
+}
+
+export const sourcesApi = {
+  browse: (path?: string | null) => call<BrowseListing>(`browse${path ? `?path=${encodeURIComponent(path)}` : ''}`),
+  /** opens the folder only when it holds a film: else a SourceError with code 'no-film' (or 'not-found') */
+  openExisting: (path: string) => call<{ project: { id: string } }>('projects', 'POST', { path, create: false }).then((r) => r.project),
+  startFetch: (url: string) => call<{ job: FetchJob }>('projects/fetch', 'POST', { url }).then((r) => r.job),
+  fetchJob: (id: string) => call<{ job: FetchJob }>(`projects/fetch/${encodeURIComponent(id)}`).then((r) => r.job),
+  cancelFetch: (id: string) => call<object>(`projects/fetch/${encodeURIComponent(id)}`, 'DELETE'),
+  examples: () => call<{ examples: Example[] }>('examples').then((r) => (seen.examples = r.examples), () => seen.examples ?? []),
+  /** an example's folder on this computer, fetched when needed (for an agent to read how it is made) */
+  exampleFolder: (id: string) => call<{ folder: string }>(`examples/${encodeURIComponent(id)}/folder`, 'POST').then((r) => r.folder),
+  skills: (projectId?: string | null) => call<{ skills: SkillEntry[] }>(`skills${projectId ? `?project=${encodeURIComponent(projectId)}` : ''}`)
+    .then((r) => { seen.skills.set(projectId ?? '', r.skills); return r.skills; }, () => seenSkills(projectId) ?? []),
+  setSkillCover: async (name: string, cover: string | null, projectId?: string | null): Promise<string | null> => {
+    const path = `skills/${encodeURIComponent(name)}/cover${projectId ? `?project=${encodeURIComponent(projectId)}` : ''}`;
+    const result = await call<{ cover: string | null }>(path, cover === null ? 'DELETE' : 'PUT', cover === null ? undefined : { cover });
+    for (const [key, skills] of seen.skills) seen.skills.set(key, skills.map((skill) => skill.source === 'mine' && skill.name === name ? { ...skill, cover: result.cover ?? undefined } : skill));
+    return result.cover;
+  },
+  /** a skill turned on or off for every project; whoever lists skills (the gallery, the desktop's chat) reads them again */
+  setSkillOn: async (name: string, on: boolean): Promise<void> => {
+    await call<{ on: boolean }>(`skills/${encodeURIComponent(name)}/on`, 'PUT', { on });
+    for (const [key, skills] of seen.skills) seen.skills.set(key, skills.map((skill) => {
+      if (skill.name !== name) return skill;
+      const { off: _was, ...rest } = skill;
+      return on ? rest : { ...rest, off: true as const };
+    }));
+    window.dispatchEvent(new Event(SKILLS_CHANGED));
+  },
+  /** an official skill installed (it starts on) or uninstalled; whoever lists skills reads them again */
+  setSkillInstalled: async (name: string, installed: boolean): Promise<void> => {
+    await call<{ installed: boolean }>(`skills/${encodeURIComponent(name)}/installed`, 'PUT', { installed });
+    window.dispatchEvent(new Event(SKILLS_CHANGED));
+  },
+  /** one of the person's own skills, or a project's, moved to the trash */
+  removeSkill: async (name: string, projectId?: string | null): Promise<void> => {
+    await call<object>(`skills/${encodeURIComponent(name)}${projectId ? `?project=${encodeURIComponent(projectId)}` : ''}`, 'DELETE');
+    window.dispatchEvent(new Event(SKILLS_CHANGED));
+  },
+  /** asked as Studio opens, so a gallery opened later shows its examples and skills at once */
+  preload: () => { void sourcesApi.examples(); void sourcesApi.skills(null); },
+  locate: (id: string, path: string) => call<{ project: { id: string } }>(`projects/${encodeURIComponent(id)}/locate`, 'POST', { path }).then((r) => r.project),
+};
+
+/** Whether what was pasted looks like a repository's address (the server checks it for real). */
+export function looksLikeRepoUrl(text: string): boolean {
+  return /^(https:\/\/)?(www\.)?(github|gitlab)\.com\/[^/\s]+\/[^/\s]+/i.test(text.trim());
+}
+
+/** A size as people read it: "820 KB", "12.4 MB", "1.2 GB". */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 1024 * 1024) return `${Math.max(0, Math.round((bytes || 0) / 1024))} KB`;
+  if (bytes < 1024 ** 3) return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+  return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+}
+
+/**
+ * How fast a download goes, in bytes a second: what came over the last few seconds (`windowMs`), so a stall shows
+ * soon and a burst does not jump it. Null until it has a second to go on.
+ */
+export function createSpeedMeter(windowMs = 5000): (bytes: number, at: number) => number | null {
+  const samples: { at: number; bytes: number }[] = [];
+  return (bytes, at) => {
+    /* fewer bytes than before: a new download, measured afresh */
+    if (samples.length && bytes < samples[samples.length - 1].bytes) samples.length = 0;
+    samples.push({ at, bytes });
+    while (samples.length > 2 && at - samples[1].at >= windowMs) samples.shift();
+    const span = (at - samples[0].at) / 1000;
+    return span >= 1 ? Math.max(0, (bytes - samples[0].bytes) / span) : null;
+  };
+}
+
+/** Seconds a download has left at `speed`; null when that cannot be told (no total, or nothing coming). */
+export function secondsLeft(bytes: number, total: number | null, speed: number | null): number | null {
+  if (!total || !speed || speed <= 0) return null;
+  return Math.max(0, (total - bytes) / speed);
+}
+
+/** A length in seconds as m:ss. */
+export function formatSeconds(seconds: number): string {
+  const total = Math.max(0, Math.round(seconds));
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
+}
+
+/**
+ * The breadcrumbs from `root` (the home folder, shown by `rootName`) to `path`: each a name and the folder it opens.
+ * Paths with / or \ alike; a path not under `root` is one crumb.
+ */
+export function pathCrumbs(path: string, root: string, rootName = '~'): { name: string; path: string }[] {
+  const sep = path.includes('\\') && !path.includes('/') ? '\\' : '/';
+  const trim = (p: string) => (p.length > 1 && (p.endsWith('/') || p.endsWith('\\')) ? p.slice(0, -1) : p);
+  const at = trim(path);
+  const top = trim(root);
+  const inside = at === top || at.startsWith(top === sep ? top : `${top}${sep}`);
+  if (!inside) return [{ name: at, path: at }];
+  const crumbs = [{ name: rootName, path: top }];
+  let walked = top;
+  for (const part of at.slice(top.length).split(sep).filter(Boolean)) {
+    walked = `${walked}${sep}${part}`;
+    crumbs.push({ name: part, path: walked });
+  }
+  return crumbs;
+}
+
+/** The words for a failed fetch, by its code (i18n keys under projects.fetch); null: say the server's own message. */
+export function fetchErrorKey(code: string | null | undefined): string | null {
+  switch (code) {
+    case 'url':
+    case 'host':
+    case 'access':
+    case 'network':
+    case 'ref':
+    case 'no-folder':
+    case 'no-film':
+    case 'too-big':
+    case 'timeout':
+    case 'git':
+      return `projects.fetch.error.${code === 'no-folder' ? 'noFolder' : code === 'no-film' ? 'noFilm' : code === 'too-big' ? 'tooBig' : code}`;
+    default:
+      return null;
+  }
+}
+
+/** The words for where a fetch is (i18n key under projects.fetch). */
+export function fetchPhaseKey(phase: FetchPhase): string {
+  return `projects.fetch.phase.${phase}`;
+}
+
+/**
+ * Wait on a fetch job until it is done or failed, telling each state on the way. `stop` ends the waiting (the job runs
+ * on unless cancelled). `get` and `wait` are the API's and a timer, so a test can drive it.
+ */
+export function followFetch(
+  first: FetchJob,
+  onJob: (job: FetchJob) => void,
+  { get = sourcesApi.fetchJob, every = 400, wait = (ms: number) => new Promise<void>((done) => setTimeout(done, ms)) }: {
+    get?: (id: string) => Promise<FetchJob>;
+    every?: number;
+    wait?: (ms: number) => Promise<void>;
+  } = {},
+): { stop: () => void; done: Promise<FetchJob | null> } {
+  let stopped = false;
+  const done = (async () => {
+    let job = first;
+    onJob(job);
+    let misses = 0;
+    while (!stopped && job.state === 'running') {
+      await wait(every);
+      if (stopped) break;
+      try {
+        job = await get(job.id);
+        misses = 0;
+      } catch (e) {
+        /* Studio restarting: a few misses are waited out; a job it no longer knows has ended */
+        if (++misses < 10 && !(e instanceof SourceError && e.status === 404)) continue;
+        job = { ...job, state: 'failed', error: e instanceof Error ? e.message : String(e), code: 'lost' };
+      }
+      if (!stopped) onJob(job);
+    }
+    return stopped ? null : job;
+  })();
+  return { stop: () => { stopped = true; }, done };
+}
+
+const COLLAPSE_KEY = 'openfilm.projects.examplesCollapsed';
+/** Whether the person folded the examples away (kept in this browser). */
+export function examplesCollapsed(storage: Pick<Storage, 'getItem'> | null): boolean {
+  try { return storage?.getItem(COLLAPSE_KEY) === '1'; } catch { return false; }
+}
+export function setExamplesCollapsed(storage: Pick<Storage, 'setItem' | 'removeItem'> | null, collapsed: boolean): void {
+  try {
+    if (collapsed) storage?.setItem(COLLAPSE_KEY, '1');
+    else storage?.removeItem(COLLAPSE_KEY);
+  } catch { /* not kept */ }
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/projects-page.ts

@@ -0,0 +1,40 @@
+/**
+ * Small rules of the Projects page: how long its list is waited for, and when a card asks again for a poster that is
+ * still being drawn.
+ */
+
+/** How long the list is waited for before the page says it could not load it (and offers to try again). */
+export const LIST_WAIT_MS = 15_000;
+
+/** What `promise` gives, or a failure once `ms` have passed without it. */
+export function within<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((done, fail) => {
+    const timer = setTimeout(() => fail(new Error(`no answer within ${ms / 1000} s`)), ms);
+    promise.then(
+      (value) => { clearTimeout(timer); done(value); },
+      (error: unknown) => { clearTimeout(timer); fail(error); },
+    );
+  });
+}
+
+/**
+ * A card's poster that did not come (still being drawn, which Studio answers at once rather than hold the browser's
+ * connection): asked for again after this many ms, `tried` times so far; null: given up (the card keeps its face).
+ */
+export function posterRetryDelay(tried: number): number | null {
+  return tried < 4 ? 4000 * 2 ** tried : null;
+}
+
+/** The poster's address for try `n` (0: the first), so the browser asks Studio again rather than its cache. */
+export function posterTry(url: string, n: number): string {
+  return n ? `${url}${url.includes('?') ? '&' : '?'}try=${n}` : url;
+}
+
+/**
+ * Whether a click on a card opens it: not the second click of a double-click (`detail` 2 or more). The first click
+ * opened something already, a folder say, and what stands under the pointer now was not aimed at. A key press (Enter,
+ * Space: `detail` 0) opens.
+ */
+export function opensOnClick(event: { detail: number }): boolean {
+  return event.detail < 2;
+}