tracker

10.8 KB

1. # Franchises and timelines (tracker.worldapi.org#19, mission 020 (old 066))
3. Creator: "we have franchises, and timelines, and some franchises have multiple timelines ... make them sortable by timeline or
4. release date at shows the release date of the last episode counts. in a show or movie page we show a franchise widget with
5. < Prequel | TimelineName | Sequel > and if the timeline is part of a franchise that franchise is above it and when you click on
6. it you get the franchise index." Names: "Franchise", "Timeline"; navigation `/franchises`.
8. ## Data (`franchises.hl`, new tables — nothing in `shows.db` changes)
10. | Table | Fields |
11. |---|---|
12. | `franchises.db` (`!slug`) | `name`, `slug`, `shortId` (always null for now), `summary`, `created` |
13. | `timelines.db` (`!slug`) | `name`, `slug`, `franchise` (@id or null), `order` [show @id …] (in-world order), `source` (`tmdb`/`editor`/`seed`), `tmdbCollection` (TMDB id or null), `orderKind` (`in-universe`/`release`/none — #40; shown as "· in-universe order" beside the count), `supersededBy` (#40: @id of the curated timeline that holds ALL its titles → hidden), `created` |
14. | `franchiseseed.db` | #40: what the curated seed made — `kind` (`franchise`/`timeline`/`collection`/`missing`), `key`, `ref` (@id), `order` + `franchise` (what it last wrote), `created`, `why`, `at` |
15. | `collectionchecks.db` | pk = the movie's show @id; `collection` (TMDB id or null), `why` (`collection`, `collection known`, `no collection`, `TMDB 404`, `collection 404`), `at` — the seed's progress |
17. * Slugs like the shows' urlSegment: `Star Trek — Prime` → `Star-Trek-Prime`; taken → `-2`, `-3`; never `edit`.
18. * A title may be in several timelines → one widget per timeline. `byShow` (show @id → [timeline @id]) is built at start
19. (`ensureFranchises`, one scan) and kept current by every edit.
20. * Inspect: the pages (`/franchises` lists every timeline with its count), or a small .hl script opening
21. `new MPackDB(file = '<copy>/timelines.db', primaryKey = '@id', indexes = ['!slug'])` + `find(null, null)` — ONLY on a copy
22. or with the app stopped (opening a table rewrites its files, hybriel#40).
24. ## Ordering
26. * **Timeline** = `order` as edited (the seed: TMDB collection parts by `release_date`).
27. * **Release** = a movie's `release`; a SERIES' LAST episode: the newest one already out (≤ today, UTC), else the newest
28. announced one, else the series' own `release`. No date → last. Equal dates keep the timeline order. Shown per row as
29. `1996-11-18` / `last episode 2020-06-15`.
30. * Franchise index: its timelines oldest first (by their earliest release).
31. * Public like all lists (mission 010 (old 054)): pages and prequel/sequel links skip titles that are not `adult == false`; the editor
32. shows every title.
34. ## Pages
36. | Route | Component | |
37. |---|---|---|
38. | `/franchises` | `components/franchises.hl` | franchises (→ index, n timelines), then the timelines without one (TMDB collections) with n titles; creator: "Edit" |
39. | `/franchises/<slug>` | `components/franchise.hl` | the index: name, summary, each timeline a header (name → its page, count, `Timeline | Release` toggle) + its rows |
40. | `/timelines/<slug>` | `components/franchise.hl` | one timeline, its franchise above it; creator: "Edit" |
41. | `/franchises/edit` | `components/franchiseedit.hl` | creator: new franchise (name, summary), new timeline (name → its editor), find a timeline by name |
42. | `/timelines/<slug>/edit` | `components/timelineedit.hl` | creator: franchise chips (None + all; a tap attaches), rows ↑ ↓ ✕, "Add titles" (search.hl index) |
43. | widget on `/shows/<slug>` | `components/franchisewidget.hl` | composed by `components/show.hl` under the header: franchise above, `‹ Prequel | name | Sequel ›`, the title under each side, a missing side greyed out (`span.off`) |
45. The sort toggle is client-only (`flatRows` is pure; both orders come with the page). One flat row list (`head`/`item`
46. rows) instead of a nested for (hybriel#86).
48. **Editor = the creator only**: `isEditorSession` = the signed-in user's ident id is in `TRACKER_EDITORS` (default `az5b2`).
49. Every editing face (`fedCreateFranchise`, `fedCreateTimeline`, `tedSetFranchise`, `tedMove`, `tedRemove`, `tedAdd`) checks it
50. again server-side; `fedFindTimelines` / `tedSearch` are public reads. Not built: rename/delete of franchises or timelines,
51. editing a franchise's summary (open point).
53. ## The seed (TMDB movie collections)
55. In the app, own `every(0.1)` clock (`project.hl collectionTick` → `franchises.hl seedStep`), ONE movie per step:
57. 1. `GET /movie/<tmdbId>` → `belongs_to_collection` (none → check row `no collection`; 404 → `TMDB 404`; other failure →
58. back of the queue, ≤ 2 retries per start).
59. 2. A collection seen before (`collectionsDone`, from check rows + timelines) → just a check row, no further request.
60. 3. Else `GET /collection/<id>` → parts sorted by `release_date`, mapped to OUR non-adult movies by tmdbId. **≥ 2 → one
61. timeline** (`source = 'tmdb'`, no franchise); < 2 → none (`small`). Every matched part gets a check row at once, so its
62. own details request is never made.
64. Pause after a step: 260 ms × requests made (≤ 40 / 10 s, like the adult backfill). Waits while the daily sync or the adult
65. backfill runs. Queue at start = every movie with a tmdbId, `adult != true`, without a check row → resumes after a restart;
66. nothing to do → one log line. Persisted every `TRACKER_COLLECTIONS_PERSIST_EVERY` (25) steps and at the end. A hand-edited
67. timeline is never touched. Log: `collections: start, N movies to check`, every `TRACKER_COLLECTIONS_LOG_EVERY` (500)
68. `collections: pos/N movies, checked= timelines= titles= small= noCollection= notFound= requests= errors= retries= seconds=`,
69. `collections done: …`. `TRACKER_COLLECTIONS=0` switches it off (off too without `TMDB_READ_TOKEN`).
71. Re-seed (e.g. after many imports): delete `collectionchecks.db*` with the app stopped — existing collection timelines are
72. skipped (their `tmdbCollection` is known); NEW parts of an existing collection are not added (open point).
74. Real data: STATUS.md, ticket #19.
76. ## Test
78. * Gate: `tests/franchises.mjs` (own storage `.scratch/franchise-store`, fixture `tests/seed-franchises.hl` on top of
79. `tests/seed-show.hl`, fake TMDB `collections`): seed + resume + pacing, widget (ends, client-side Sequel click, franchise
80. above), `/franchises`, index sort both ways (series by last episode), editor only for `TRACKER_EDITORS`, 390/1280 no
81. sideways scroll, screenshots with `TRACKER_GATE_SHOTS`.
82. * `tests/browser.mjs` runs with `TRACKER_COLLECTIONS=0` (its fake TMDB request counts must not see the seed).
83. * Real data: `tests/realdata-066.mjs` (procedure in STATUS.md).
85. ## Since the merge (mission 023 (old 070))
87. * Headings are #20's typed ones: "Franchises" (blueLight), "Franchise | <name>", "Timeline | <name>" (greenLight), also on the
88. timeline editor. Title links use `shows.hl titlePath` (`/movies/…`, `/series/…`, `/shows/…`).
89. * The seed waits for the daily sync, the adult backfill, the details repair, the kind backfill AND the credits job (one TMDB
90. pacing at a time): on the first start after the deploy it runs last (~32–37 min after the kind backfill's ~16–21 min).
92. ## The curated seed (tracker#40, mission 034)
94. Creator: "you never build timlines and franchises". Architect: a curated seed for the big franchises from a hand-written order file
95. in the repo (data, not code), movies AND series, in-universe order where known, else release; missing titles fetched via the search
96. import; a resumable job on deploy; the editor stays for corrections.
98. * **Data**: `data/franchises.json` (`TRACKER_FRANCHISE_FILE`). Per franchise `name`, `summary`, `collections` (TMDB collection ids
99. whose collection-seed timelines join it), `timelines` [{ `name`, `order` (`in-universe`|`release`), `titles` [[`tv`|`movie`, TMDB
100. id, "title (year)"]] }]. The ids were checked against themoviedb.org (title + year) on 2026-10-04. A title may sit in several
101. timelines (Terminator's alternate lines all start with T1 + T2; Peacemaker in DCEU and DCU).
102. * **Job** (`lib/jobs.hl franchiseSeedTick` → `lib/franchiseseed.hl`): waits for the merge, sync, backfills, repair, kinds, credits
103. AND the collection seed; prepare = the file's titles we lack (`search.hl titleIdByTmdb`, a tombstone → its keeper) minus the
104. remembered 404s; one import per step (`details.hl importWithCredits` — the search's "Add": complete with seasons, poster, ids,
105. TVmaze, cast + crew), pause `tmdb.hl pauseMsAfter`; queue done → ONE build step (no TMDB): franchise (seed row → else the
106. creator's of that name, adopted → else new), collections attached (only a timeline without franchise, once), each timeline:
107. no row → the creator's of that name? kept : new (`source = 'seed'`, needs ≥ 1 title, else `empty`); row → order/franchise as
108. the seed last wrote? update to the file : `kept`.
109. * **Editor changes win**: comparing the timeline with the seed's own record — any ↑ ↓ ✕, added title or franchise chip by the
110. creator makes it "edited", never written again (also a merge.hl id swap counts as an edit — rare). The creator can rename
111. nothing yet (open point of #19), so a renamed file timeline would be made anew.
112. * **Log**: `franchise seed: start, 17 franchises, 31 timelines, 285 titles in the file — N we have, M to import, K TMDB lacks`,
113. each import's `search import: …`, every 25 imports a progress line, `franchise seed done: franchises=… (created= adopted=)
114. timelines=… (created= updated= unchanged= kept= empty=) collections= titles= had= imported= failed= missing= placed= requests=
115. tvmazeRequests= seconds=`.
116. * **Re-run after editing the file**: just restart — new titles are imported, unedited seeded timelines follow the file.
117. To make the seed forget everything: delete `franchiseseed.db*` with the app stopped (it then ADOPTS its own franchises by name
118. and keeps its own timelines as "the creator's" — so delete those too if a clean re-seed is wanted).
119. * **Test**: gate `tests/franchiseseed.mjs` (24 checks); real copy `tests/realdata-m034.sh` (STATUS.md mission 034).
120. * **Superseded collections** (team lead: no second widget, e.g. First Contact = TNG Collection + Prime): a TMDB collection
121. timeline whose titles are ALL in one curated (`source = 'seed'`) timeline gets `supersededBy` = that timeline — no widget, not on
122. /franchises nor a franchise index, not counted; NOT deleted: `/timelines/<slug>` still answers and the editor's finder lists it
123. as "… · hidden: all in <name>". Decided by `franchises.hl seededCoverOf`; set by the collection seed when it MAKES a timeline
124. (`collections done: … superseded=N`) and by the curated build for existing ones (`superseded=`, `unsuperseded=` when the cover
125. is gone again). A collection only PARTLY in a curated timeline stays shown and joins that franchise (`joined=`). Real copy
126. 2026-10-04: 24 superseded (STATUS mission 034), First Contact shows ONE widget (Star Trek — Prime, STAR TREK above).