Introduction

Falcon is a rebuild of the Eagle asset manager in Rust, written to learn how Eagle works.

Each chapter in the first part describes one piece of Eagle. It covers what Eagle does, with every claim marked observed or inferred, and then how falcon implements it.

• Observed claims come from Eagle’s own files: a real library on disk, or REA analysis of app.asar.
• Inferred claims are conclusions drawn from those files that haven’t been checked directly.

Falcon is written from that behaviour. It doesn’t copy Eagle’s code.

The second part, The desktop app, describes falcon’s desktop app: its window, viewers, keys, preferences, themes and how it opens and saves libraries.

Status

Falcon is early alpha and unsigned. PARITY.md compares it with Eagle 4.0.0 feature by feature, checked against falcon’s code. Of Eagle’s 912 features outside the online set, 905 are done and 7 are accepted differences; none is partly done or missing. That is about 99% done. Another 32 need an online service, an account or Eagle’s plugin system and are counted separately. ROADMAP.md lists what is left and what comes later.

Falcon handles exactly Eagle’s set of file formats. FORMATS.md lists each one and its status. Falcon has no plugin system: Actions and Export in Format are built into the app, and PLUGINS.md lists the plugins Eagle provides that falcon could build later.

Working today

• Import with thumbnails and colour palettes, folders with their structure, paste, drag and drop, and screen capture.
• Folders, tags with a tag picker, smart folders, Quick Access, ratings, notes, undo and batch editing.
• Keyword, filter and colour search, with marquee selection in four layouts.
• Viewers for images at full resolution, video (with an FFmpeg fallback that includes AV1), audio, fonts, a text editor, PDFs with their reader tools, interactive 3D models with textures, normal, bump and emissive maps and transparency, full IFC through web-ifc, PSD and AI at full resolution, and live web pages and MHTML.
• Preferences panes, the interface in eight languages (machine-written, waiting for a native read), sound effects, Actions, and Export in Format.
• The local HTTP API and the command-line tool.

Not there yet

• Some File ▸ New templates, normal and bump maps on 3D models, and a check on screen of some newer features (see ROADMAP.md).
• Eagle’s plugins.
• Signed releases, and the parts of the app that need macOS on Windows and Linux (see Windows).

Running the docs

scripts/docs.sh

This builds the API docs with cargo doc and serves the book at http://localhost:3000, reloading on changes.

Workspace

Build a launchable Falcon.app with scripts/bundle.sh.

Library format

An Eagle library is a folder ending in .library. All state is plain JSON next to the files themselves. There is no database.

Assets.library/
├── metadata.json        folder tree and library-wide settings
├── mtime.json           item id → modification time, plus "all"
├── tags.json            historyTags, starredTags
├── saved-filters.json
├── backup/              JSON snapshots
├── Icon                 empty file (the macOS custom-icon marker)
├── icon.png             the library's own icon (optional)
└── images/
    └── <ID>.info/
        ├── metadata.json            one item
        ├── <name>.<ext>             the original file
        └── <name>_thumbnail.png     only for some items

icon.png is the picture the library switcher shows beside the library’s name. Falcon’s Change Icon scales the chosen image so its shorter side is 64 px, saves it as PNG next to the library’s other files and renames it over icon.png, so an old icon is never left half written. Remove Icon deletes the file. The HTTP API serves the same file.

Library metadata.json (observed)

The top-level keys, in this order, are folders, smartFolders, quickAccess, tagsGroups, modificationTime and applicationVersion.

folders is a recursive tree. Eagle rebuilds every node in a fixed key order each time it saves, and leaves out keys whose value is unset. The fixture’s folders carry only the always-present keys.

Sort keys (observed): IMPORT, MTIME, BTIME, NAME, EXT, FILESIZE, RESOLUTION, RATING, DURATION and RANDOM are in the folder menu. TAGS is in the main sort menu, and MANUAL (a hand-arranged order, kept per folder in each item’s order map) is honoured when present. No orderBy key means the folder follows the global sort. Choosing a sort sets sortIncrease to true if it was unset. Clearing it deletes both keys.

Icons (observed): the picker offers 161 names. Falcon lists them in falcon_library::model::FOLDER_ICONS, spelled exactly as Eagle stores them (including excalmation, airplan and rophy). Picking the first, blank entry deletes the key. A new subfolder takes its parent’s icon and iconColor. Falcon’s emoji folder icons are not part of the format: Eagle builds a style class from icon, so an emoji there would have no artwork. Falcon keeps them in its own app data, keyed by folder id, so another Mac or Eagle does not see them, and it never writes them to metadata.json.

Passwords (observed): password is btoa(password), plain base64 with no hashing. btoa reads each UTF-16 unit as one byte and throws on anything above U+00FF. Eagle doesn’t escape the text first, so a password with such characters can’t be set at all. é is stored as 6Q==, not as the base64 of its UTF-8 bytes. Unlocking checks atob(password) against the typed text. Removing a password deletes both keys from the in-memory folder, but the save writes password || "", so on disk a folder that never had a password and one whose password was removed look the same: "password":"","passwordTips":"". Falcon refuses empty and non-Latin-1 passwords.

Ordering: the array order is the sidebar order. Dragging a folder between siblings moves it in its parent’s children. Dropping a folder onto another one appends it to that folder’s children.

Sort by title (observed in code): a folder’s context menu has a “Sort By” submenu with four commands: title A→Z or Z→A, for the current level or for all levels. The current level is the clicked folder’s siblings, that is, its parent’s children (or the root list). All levels sorts the root list and then every children array in the tree. Eagle asks for confirmation, sorts the arrays in place and saves. No flag is stored, and modificationTime is left alone. The comparison lowercases both names and uses localeCompare with numeric ordering, so folder 2 comes before Folder 10. Z→A is the A→Z result reversed.

Falcon: Library::sort_subfolders(parent, SubfolderSort { descending, all_levels }) sorts parent’s subfolders (None for the root list), and with all_levels every level below them too. Pass the clicked folder’s parent for Eagle’s “current level”, and None with all_levels for its “all levels”. Names compare with search::natural_cmp, the comparison falcon also uses for title sorts. Unlike the ICU collation Eagle uses, it orders accented letters by code point (inferred to matter only for non-ASCII names). Eagle’s comparator calls an empty name equal to everything. Falcon sorts empty names first, because Rust’s sort needs a consistent order.

The writer (observed): the background process writing metadata.json deletes these runtime keys from every folder: covers, images, folders, newFolderName, editable, pinyin, __root, extendTags and $$hashKey. From smart folders it deletes only newFolderName, editable and $$hashKey. It then writes {folders, smartFolders, quickAccess, tagsGroups, modificationTime: Date.now(), applicationVersion}. It refuses to write, and reports a sync conflict, when the file’s modificationTime is newer than the one Eagle loaded. Falcon still models extendTags and pinyin so that a file holding them round-trips.

Names (observed): every save NFC-normalises folder, smart-folder and tag-group names. Renames are cut to 1024 UTF-16 units; falcon cuts at 1024 characters. Falcon normalises and cuts every name it writes. A rename drops any stale pinyin.

Tag groups (observed in code)

tagsGroups is an array in sidebar order. The fixture has none. Each save rebuilds every entry as:

• Creating a group: a new group goes at the end. Creating one from selected tags leaves those tags in their other groups.
• Adding tags: adding through the tag manager moves each tag, taking it out of any other group, so a tag normally belongs to one group.
• Removing tags: taking tags out of a group leaves them on their items.
• Deleting a group: Eagle asks whether to delete the group’s tags from every item too.
• Reordering: the sidebar is drag-sortable, and the array follows it. The drag takes the group out of the array and inserts it at the drop index, which is counted after the removal. This is what falcon’s reorder_tag_group(id, index) does.
• Description: the tag manager shows an editable box under a selected group’s name. On blur, Eagle saves the box’s HTML if it changed: a trailing <br> and any <div> wrappers are stripped, and & is turned back into &. Clearing the box writes "", so the key stays once it has been set. Groups made by the tag manager have no description key until then. Falcon’s set_tag_group_description(id, text) writes the given string, "" included.
• Other tag edits: renaming or deleting a tag also updates every group.

None of these edits touch the folders’ modificationTime. The library’s top-level modificationTime is stamped when metadata.json is written.

tags.json (observed in code)

{"historyTags":[...],"starredTags":[...]}, compact, with no trailing newline. Eagle writes it five seconds after a change, through an atomic write.

• historyTags: recently used tags, latest first, at most 120. Adding a tag (the tag picker, pasting tags, the inspector) moves it to the front; adding several moves each in turn, so the last one leads. Eagle’s imports with tags move them as a batch, so there the first one leads (falcon’s imports leave the history alone). A tag taken off its last item is dropped. Renaming or merging a tag renames it in place, or drops it when the new name is already listed (the same rule holds for starredTags and each tag group’s tags); deleting a tag removes it. Clear Tag History empties the list.
• starredTags: starred tags, most recently starred first.

Tag groups are not in this file but in tagsGroups of the library metadata.json (see above).

saved-filters.json (observed in code)

A JSON array in menu order, [] in the fixture. Eagle writes it compact with JSON.stringify and no trailing newline. Each entry is {"name": …, "rule": {…}}, with no id and no timestamp, and Eagle finds entries by position. Saving a filter first re-reads the file, then appends. A rename ignores empty names. The menu is drag-sortable, and the array follows it.

rule is a deep copy of the filter panel’s rules, made by JSON.parse(JSON.stringify(defaults)) and then edited, so undefined values are dropped and integer-like keys come first (rating is written "0" to "5", and shape starts with "34","43","169","916"). keyword is added at the end when a search was active. Applying a filter replaces each top-level rule key, a shallow {...defaults, ...rule}. The tag and folder logic (OR, AND or EQUAL) is a panel setting that isn’t saved.

Falcon’s SavedFilter::to_filter returns the filter, the keyword and the AI rules, each kept whole so that a save writes back the same bytes (SavedAiRules::write_to). SavedFilter::rule_from_filter builds the full default rule object with falcon’s rules filled in. It writes sizes in KB, and folder entries as {id, name}, since Eagle only reads id back. Durations go in the largest of h, m and s that keeps both bounds whole. A Date Imported or Date Modified range goes in import.range with import.type: "range", where Eagle reads both; only when the two rules have different ranges does falcon also write mtime.range, which it reads back first and Eagle ignores (Eagle then applies the imported range to both). A range with an unset end reads as (0, 0), which passes nothing, as in Eagle. Reading a font rule fills the FontFilter with the fonts in ~/Library/Fonts/EagleApp and in falcon’s own ~/Library/Fonts/Falcon (to_filter_with_fonts takes them from the caller); Eagle reads only the first, so a font activated by falcon counts as installed in falcon and not in Eagle. Both directions are falcon’s own reading of Eagle’s code, checked by unit tests against hand-built rules, not against a file Eagle wrote (inferred).

Item metadata.json (observed)

Files Eagle can’t preview. For items such as .tex, .md, .py, .csv and .epub files, Eagle leaves out height, width and palettes. It may also add keys such as noPreview and deletedTime before lastModified. Seen in real libraries: 1,456 of 2,632 items in one, 2 EPUBs in another.

Damaged records. A record can be unreadable, for example 604 zero bytes after a cloud sync went wrong (seen once in a real library).

Falcon treats every key but id as optional. It remembers each record’s key order and writes keys back in that order, and leaves out a field the record didn’t have while it still holds its default. New items use the order in the table. An unreadable record is skipped when the library opens: falcon lists it in Library::skipped, never writes to it, and save_to copies its folder unchanged. Checked on four real libraries (3,905 readable records): every record saves back byte for byte.

Comments (observed in code)

Region notes on images and timed notes on video and audio live in an optional comments array on the item. JavaScript adds the key the first time a comment is made, so it comes after the keys an item starts with. None of the fixture’s items has comments. Eagle’s filter panel calls these “annotations”. They are separate from the item’s annotation string, which is the note.

Every comment change saves the whole item, so the item’s own lastModified and mtime.json move as in any edit. Deleting the last comment leaves "comments":[].

Falcon models these as model::Comment. Item::comments() and Item::set_comments() read and write the key without moving it or any other key in extra. On Library, add_comment fills in the id and time, and keeps timed notes sorted (a new note goes after others at the same time). update_comment replaces a comment by id, and delete_comment removes one. Falcon re-serialises each comment in Eagle’s key order: id, region or duration, annotation, lastModified, then unknown keys.

Manual order (observed in code)

A folder sorted MANUAL keeps its hand-arranged order in each item’s optional order object: order[<folder id>] is a decimal string, such as "1789479235636.5". JavaScript adds the key the first time an item is dragged, so it comes after the keys the item started with. A new folder id goes at the end of the object.

• Sorting: the MANUAL sort compares these values as strings, largest first. An item with no entry (or an empty one) uses its modificationTime turned into a string, so undragged items fall in import order, newest first. sortIncrease: false reverses the list. As strings, "999" sorts above "1000". This never matters for real timestamps, which all have 13 digits.
• Dragging: Eagle works in exact decimals (a big-number library). Divisions round to 20 places, with halves rounded away from zero. Values are written in the shortest form (toPrecision() with no argument, so "2500", not "2500.0"). Dropping n items between neighbours prev and next sets middle = (prev + next) / 2 and step = (middle - next) / n. The last dragged item gets middle, and each earlier one gets middle + step × k, which moves towards prev. Before the first item, prev is the first item’s value + 1 (- 1 when descending). After the last item, next is the last value - 1 (+ 1 when descending). A neighbour with no entry counts as its modificationTime.
• Collisions: before placing, Eagle checks whether two of the other items share a value. If they do, every item i (counting from 0 in the current view) that has an entry gets value - i × 10^-(digits in the view's item count + 1). The step is a JavaScript float multiplication, float noise included (0.01 × 57 gives 0.5700000000000001). Eagle reads the direction flag here before it is set, so the values always step down.
• Side effects: dragged items save as an ordinary edit (lastModified bumped). A folder that wasn’t on MANUAL switches to MANUAL with sortIncrease: true.
• Dropping onto one of the dragged items, or into a view with no other items, throws in Eagle, so nothing changes.

Falcon: Item::manual_order(folder) reads the value as a number, Item::manual_sort_key(folder) gives the string the sort compares, and Item::set_manual_order writes one. search::sort_manual(items, folder, increase) is the MANUAL sort. Library::move_items_manually(folder, ids, before) moves items as a block before another item (None for the end), using the same decimal arithmetic (manual::Dec) and collision handling. It works out the order over all untrashed items in the folder, where Eagle uses the items currently shown (inferred to be the same when no filter is on). Moving items that aren’t in the folder, or placing them before one of themselves, is refused.

mtime.json (observed)

An object that maps item IDs to ms times, ending with "all". In the fixture it lists only 32 of the 91 items, yet all is 91. So all is the library’s total item count, not the number of entries.

Eagle’s Empty Cache and Reload reads the library again and rewrites mtime.json from what it read. Falcon’s Library::rebuild_mtime() does the same from the items in memory: one entry per item that has a lastModified, in id order, then all set to the item count.

Encoding (observed)

Eagle writes compact JSON with no trailing newline and keeps keys in insertion order.

How falcon does it

falcon_library::Library::open checks the library’s version (see Newer libraries and outside changes) and loads every JSON file into typed structs. Library::save_to writes them back out.

• Lossless: unknown keys are kept in an extra map on each struct.
• Number format: ratio stays a raw serde_json::Number, so 45 isn’t rewritten as 45.0.
• Key order: each item remembers whether width came before height.

Together these make every JSON file in the test fixture re-serialize byte-for-byte, which the round_trips_byte_identically test checks.

Newer libraries and outside changes

Version check. metadata.json carries the applicationVersion of the Eagle that last saved it. Falcon reads and writes the format of Eagle 4.0.0 (library::APP_VERSION), and Library::open refuses a library whose applicationVersion is newer, with Error::NewerLibrary, as Eagle refuses a library from a newer release and asks for an update. Versions are ordered the way Eagle orders them (compare_versions): an optional leading v, then up to four dot-separated numbers compared as numbers (10.0.0 is newer than 4.0.0, and a missing number counts as 0, so 4 equals 4.0.0). A -prerelease part sorts before the release itself (4.0.0-beta.2 is older than 4.0.0, 5.0.0-beta is still newer than 4.0.0), its dot-separated parts compare as numbers when both are numbers and as text otherwise, and a shorter list sorts first. A +build suffix is ignored. A version that can’t be read is not refused.

Write guard. Library::write_metadata_file is the one place metadata.json is written while a library is open. Before writing, it reads the file on disk and refuses, writing nothing, when

• the disk copy’s applicationVersion is newer than 4.0.0 (Error::NewerLibrary), or
• the disk copy’s modificationTime is later than the one falcon last read or wrote (Error::SyncConflict). Another app or a sync tool saved the file in the meantime, and writing would lose its changes.

A disk copy that can’t be read or parsed is overwritten. Falcon’s own writes set the remembered time, so they never conflict with themselves. A refused write sets a flag that Library::take_conflict() returns once, and the app uses it to reload the library from disk (see Several libraries). In batched mode the refusal comes at the flush, and the pending set is dropped rather than retried. Every caller of the library trips the guard, the HTTP API included.

Picking up outside changes. Eagle polls metadata.json and mtime.json every 4 seconds with fs.watchFile, and falcon polls the same two files at the same interval (crates/falcon-library/src/sync.rs; the app’s polling thread is crates/falcon-app/src/watch.rs). The thread compares file times and, when one moved, reads and parses that file off the UI thread. A file caught half written doesn’t parse and is read again on the next poll. An empty mtime.json is ignored, as in Eagle, because it is being rewritten. Applying a change is quick and happens with the library locked, and it never writes, since the changes are already on disk.

• metadata.json changed: Library::take_external_metadata takes it only when its modificationTime is later than the one in memory. The folder tree, smart folders, quick access and tag groups it holds replace the ones in memory, including edits still waiting in batched mode, and its time becomes the base later writes are checked against.
• mtime.json changed: Library::sync_items compares it with the stamps in memory. An id falcon doesn’t hold is a new item and is read from its metadata.json. A larger stamp is an edited item, read again. When the all count differs from the number of items held, images/ is listed to drop items whose folder is gone and to add folders the index missed. An item that can’t be read yet, because a sync is still copying it, waits for the next poll. A pending write of an item that was replaced is dropped, since the disk copy is newer.
• Falcon’s own writes come back through the same path and change nothing, since their stamps are the ones in memory.
• A vanished library folder is reported once, and Library::discard_pending_writes() drops everything batched mode was holding, so nothing is written to where the library used to be.

Backups

Eagle keeps snapshots of the library metadata.json in backup/. Only that one file is backed up; item metadata.json files, mtime.json and tags.json are not.

How falcon does it

falcon_library::backup follows the table. Library::backup_metadata() takes a backup now (returning None when skipped), Library::backups() lists them newest first, and Library::restore_metadata_from_backup(path) restores a chosen one. Library::open_or_restore(path) opens a library and, when metadata.json can’t be read or parsed, restores the newest usable backup first, as Eagle does on launch. falcon also requires the backup to load as a LibraryMetadata, slightly stricter than Eagle’s modificationTime check (inferred to be harmless: a backup without the standard keys would break Eagle too).

Library::save_metadata and Library::flush do not take backups, because Eagle doesn’t back up on each write. FlushReport::wants_backup() says when a flush wrote mtime.json or metadata.json. Callers take the backup with backup_metadata(), or backup::backup_library(root), which needs only the library folder and so can run on another thread while the library is in use (a metadata.json caught mid-write doesn’t parse and is skipped). falcon backup <library> takes one by hand; the app schedules them (see Saving).

The second copy lives outside the library. backup::app_data_backup_name(root) names it <hash>.json, where <hash> is the 32-bit FNV-1a hash of the library path (no trailing slash) over its UTF-16 code units, as 8 lowercase hex digits, the same name Eagle gives it. The app keeps these in eagle-backup/ inside its own app data folder, ~/Library/Application Support/Falcon/eagle-backup/ on macOS, and backup::backup_library_with(root, app_backups) replaces the library’s copy with every new backup. A failure there is ignored, as in Eagle, and the copy is written through a temporary file and a rename so a reader never sees half a file. Nothing is written for a library whose folder is gone, so a backup never recreates a moved or deleted library.

Merging libraries

Eagle’s Library ▸ Import Library merges another library into the open one. Falcon’s falcon_library::library_merge follows it:

• Refusals: the library that is open is refused, a folder without metadata.json (or with one that doesn’t parse) is not a library, and a library from a newer Eagle is refused as on open.
• Folders: a top-level folder whose id the open library already has is not added again, and its subfolders go through the same test inside the existing one. New folders come in with their whole subtree.
• Smart folders and tag groups: those whose id is already present are skipped and the rest are appended.
• Items: every images/<id>.info folder the open library lacks is copied verbatim, and ones it has are left alone. The items keep their folder ids, which the merged tree now contains.

Falcon differs from Eagle in two small ways. It copies only *.info folders, not stray files in images/. And a new folder’s descendants whose ids already exist elsewhere in the open library are merged into those instead of being added a second time, so the tree never holds one id twice. Each item folder is copied under a temporary name and renamed into place, so an interrupted merge never leaves half an item.

The work is split so the app stays responsive. merge::plan(&lib, source) reads the other library and reports what would come in (MergePlan::counts()). merge::copy_items needs no lock on the open library, runs on a background thread, reports progress, can be cancelled and returns the folders copied, with the reason for any that failed. Library::finish_merge then merges the folder tree, saves metadata.json and registers the copied items in memory and in mtime.json, returning a MergeReport of folders, smart folders, tag groups and items added.

Adding to another library

Eagle’s Add to Other Library copies items, a folder, a smart folder or a tag group of the open library into another one. Falcon’s falcon_library::add_to_library follows it:

• Items: each images/<id>.info folder is copied whole. One whose id the other library already has is left alone. The copy’s metadata.json loses its folders, and its modificationTime becomes the time of the copy plus the item’s position in the selection, so the items show up as newly added, in order.
• A folder: the folder and its subfolders, ids kept, go to the top of the other library’s tree, unless it already has the folder’s id. Subfolders whose ids it has are not added twice. The items in the folder and its subfolders (not those in the Trash) are copied as above but keep their folders, and in a folder sorted by hand they also keep their modificationTime.
• A smart folder or a tag group: only the definition is added, at the top of its list, under new ids (a smart folder’s subfolders too).
• The other library’s tags.json is left alone, as Eagle leaves it.

Falcon differs in three small ways. An item copied with a folder keeps only the folder ids the other library has once the tree is merged, so no item points at a missing folder. A new folder’s descendants whose ids exist elsewhere in the other library are merged into those, as when merging libraries. And each item folder is copied under a temporary name, its metadata.json rewritten there, and then renamed into place, so the other library never sees half an item.

add_to_library::check_target refuses the open library itself, a folder that is not a library and one from a newer Eagle. copy_items needs no lock, reports progress and can be cancelled. Library::finish_add, called on the other library, adds the definition (saving metadata.json only then) and registers the copied items in memory and in mtime.json.

Inboard backups

Eagle’s File ▸ Import ▸ Inboard reads a backup folder made by the Inboard app, and falcon_library::inboard reads it the same way. The folder holds InboardBackup.json, with folders (each with a title) and items, plus the files in images/ and screenshots/.

• Folders: one top-level folder is created per Inboard folder, all of them and in order. When two share a title, items go to the later one (inboard::folder_map).
• Items: only items whose type is "image" are imported. The file is the last component of the item’s path, looked up in screenshots/ when that path runs through a /screenshots/ folder and in images/ otherwise. An image whose file isn’t in the backup is counted as missing (InboardBackup::missing) and skipped.
• What an item keeps: Inboard’s title as its name, its tags, its url, its trashed state (isTrashed other than 0, or true) and its date as the date added. A numeric date is read as milliseconds, and a string as RFC 3339 or YYYY-MM-DD HH:MM:SS ±ZZZZ.
• Folders of an item: its folders are Inboard folder titles, mapped to the new folder ids; titles that match no folder are dropped.

inboard::is_backup(dir) says whether a folder has the index, and inboard::read(dir) returns the folders and importable items. The import itself goes through the ordinary import path, so duplicate handling and thumbnails are the same as for other files.

Pixave libraries

Pixave, LittleHJ’s discontinued macOS image manager, keeps each library in a package whose name ends in .pxvlibrary. Eagle 4.0.0 has no Pixave importer: its menus have no Pixave entry and Import Folders silently skips a .pxvlibrary folder. Falcon does the same (folder_import::is_pixave_library); it doesn’t import Pixave libraries or items.

Undo

How falcon does it

falcon keeps a real history. Library::begin_transaction(label) starts recording and end_transaction() returns a undo::Transaction, or None when nothing changed. While a transaction is open, the write paths record what they replace:

• register_item (every item save and import) records the item’s first pre-edit copy, or its id as created when it didn’t exist.
• save_metadata, save_tags and save_filters record the value as last saved, once per transaction. The library keeps a copy of the last saved metadata, tags and saved_filters for this, so edits that change the fields before saving still record the old value.
• forget_item (permanent delete, empty trash) marks the transaction irreversible. The files are gone, so the app clears its undo history when such a transaction lands, as Eagle offers no undo there either.

Library::revert(tx) restores the recorded state in a new transaction and returns it, so reverting that redoes the edit. Items are saved through update_item, so a rename moves the original and thumbnail back, and lastModified moves forward, which matches Eagle’s restore (observed above). Items created in the transaction (imports) go to the trash, with their files kept. Library metadata gets a new modificationTime. Recording never changes what is written, so the fixture round trip is unaffected.

Write batching

How falcon does it

Library::set_write_mode(WriteMode::Batched) makes the item, mtime.json, metadata.json, tags.json and saved-filters.json writers mark what is dirty instead of writing. Library::flush() then writes each dirty item once, mtime.json once, and each library-wide file once, and returns a FlushReport. Because every writer serialises the whole in-memory value, the bytes after a flush are the ones immediate mode would have written last. When mtime.json or metadata.json was written, FlushReport::wants_backup() is true, and the app schedules a backup, as Eagle backs up after rewriting mtime.json (falcon also counts a metadata write, inferred harmless: the backup is skipped when the size is unchanged). The flush itself takes no backup. File renames and permanent deletes still happen at once. An item deleted before the flush is skipped. If a write fails, the pending set is kept for the next flush. Dropping a batched library with pending writes flushes it, ignoring errors. WriteMode::Immediate is the default, used by the CLI, the server and the tests. Switching back to it flushes first.

falcon writes JSON files in place rather than through a temporary file, as before.

Export (.eaglepack)

An .eaglepack is how Eagle moves items and folders between libraries.

Refs.eaglepack           a zip archive, entries stored without compression
├── pack.json            {"images": [...], "folder": {...}}
└── <ID>.info/           each item's whole info folder, as in images/
    ├── metadata.json
    ├── <name>.<ext>
    └── <name>_thumbnail.png

How falcon does it

The app writes packs on a background thread, so the work is split in two: plan_pack(&lib, source) builds pack.json and the list of item folders into a PackPlan that holds no reference to the library, and write_pack(&plan, dest, on_item) writes it, reporting each item folder added. falcon_library::pack::export_pack(&lib, PackSource::Items(ids) | PackSource::Folder(id) | PackSource::Smart(id), dest) does both and writes a pack following the table, using the zip crate with stored entries and each file’s time and Unix mode. preview_pack(&lib, pack) reads a pack without extracting it, as Eagle does before it asks: it opens the zip, adds up the uncompressed size of every entry, parses pack.json and counts how many of its items look like untrashed items already in the library, using the same duplicate key as skip_duplicates. It returns a PackPreview of items, duplicates and bytes, and fails with Error::Pack when the file isn’t a zip or pack.json is missing or has no images list. import_pack(&mut lib, pack, &PackImportOptions { folder, skip_duplicates }) imports one and returns the new item ids. Item files are moved in as they are (thumbnail included), not re-imported, as Eagle does. Differences from Eagle, all inferred to be harmless:

• falcon drops item folders ids that don’t exist after import, where Eagle would write null or keep a dangling id.
• An item whose <ID>.info folder is missing from the pack is skipped; Eagle still lists it, with no files.
• A record without isDeleted (an exported trashed item) is written back with "isDeleted": false, since falcon’s item model requires the key.
• The duplicate key covers images and videos only; audio and font keys are not implemented.

The CLI has falcon export <library> <out.eaglepack> [--folder ID | --smart ID | ITEM...] and falcon import-pack <library> <pack> [--folder ID] [--skip-duplicates].

Item and folder IDs

IDs are 13 characters of uppercase base 36, for example MVP1BZ832CIJ1.

The timestamp prefix (observed)

The first 8 characters are the creation time in milliseconds, written in base 36:

Because of this prefix, sorting IDs as strings also sorts items by creation time, as long as the prefix stays 8 characters. That holds until the year 2059.

The suffix

The last 5 characters tell apart items created in the same millisecond. Whether they are random or a counter is still being checked against app.asar.

Import pipeline

What Eagle does

Every claim is from Eagle’s plain-JS background window code (processImage in background.js). The Electron main process is V8 bytecode and was not read.

1. Stat the source (observed). size is the byte length. btime and mtime are the file’s birth and modification times as integer milliseconds, read before the copy.
2. Reject (observed). A file with no extension is refused (“File format is not recognized”), and so are unfinished browser downloads (.crdownload, .part, .download), which getExt treats as having none. Any other extension, known or not, goes ahead. So is an empty file refused, unless its extension is txt. The refusal goes to the failed-imports list; there is no dialog.
3. Name (observed). The extension is removed, the name is sanitised and trimmed, shortened to fit the file system, normalised to NFC, and replaced by _ if empty. The upload step strips / and % first.
4. Directory (observed). images/<ID>.info/ is created. The original is <name>.<ext> and the thumbnail <name>_thumbnail.png.
5. Item record (observed). isDeleted is false, url and annotation are empty, tags and folders come from the caller.
6. Copy (observed). copyFile, then utimes so the copy keeps the source’s mtime. A failed copy removes the .info folder and reports an error.
7. Thumbnail (observed). Sets width, height, noThumbnail and removeThumbnail. See Thumbnails. If it throws, the item is still added, without a thumbnail.
8. Palette (observed). Computed from the thumbnail, or from the original when noThumbnail && !removeThumbnail. When removeThumbnail is set, the thumbnail is deleted once the palette task finishes.
9. Metadata write (observed). Each write sets lastModified to the current time and writes the item’s metadata.json.

Format metadata

Eagle’s thumbnail modules (app/js/thumbs/) also add keys for some formats. New keys go after the ones already set, in the order below. In Eagle they land before lastModified and palettes. Falcon keeps unknown keys after palettes, so it writes them at the end. Eagle’s reader doesn’t depend on key order.

RAW photos (observed). These are 3fr, arw, orf, mrw, nef, nrw, raw, cr2, crw, dng, erf, pef, raf, rw2, sr2, srw, x3f and cr3. Eagle runs dcraw’s identify on the file and stores rawMetas:

• Missing values are left out. An empty object is not stored.
• JPEG, HEIC and TIFF get no rawMetas. Eagle reads their EXIF only for orientation.
• Smart-folder rules parse the strings back: the first number of aperture and focalLength, and the second number of shutter. So "2.0 sec" never matches a shutter rule.

Video (observed). resolutionWidth and resolutionHeight (copies of width and height), then duration. All come from Chromium’s <video> element. duration is in seconds with a fraction.

Audio (observed). mp3, wav, flac, ogg, aac and m4a. width 280 and height 140 (the waveform thumbnail, see Thumbnails), then duration from an <audio> element. Then bpm (observed in js/thumbs/audio.js): after drawing the waveform, Eagle mixes the decoded audio to mono and runs a bundled beat tracker (music-tempo) over it. For files over 3 minutes it analyses only the start: the first 3 minutes, or the first 2 past 10 minutes, or the first 1 past an hour. The tracker searches beat intervals of 0.3 to 1 second (60 to 200 BPM) and reports the tempo as a string with three decimals. Eagle stores it with parseFloat, so it is a JSON number such as 119.985, or 120 when whole. When the tracker finds no tempo, nothing is stored (inferred for silence, where the tracker has no beats to follow). Refresh Thumbnail recomputes it.

Fonts (observed). For ttf, otf, ttc, woff and woff2 (Eagle’s FONT_FORMATS; an .otc is a plain item), Eagle parses the file with opentype.js and stores fontMetas:

• First, one key per name table entry, in table order: copyright, fontFamily, fontSubfamily, uniqueID, fullName, version, postScriptName, trademark, manufacturer, designer, description, manufacturerURL, designerURL, license, licenseURL, preferredFamily, preferredSubfamily, and others. Each is a map from language code (en, zh, zh-TW, ja, …) to text. A Windows record replaces the Macintosh text for the same language but keeps its position.
• Then numGlyphs.
• Then support, which holds zh_CN, jp, zh_TW and kr set to true when the font has glyphs for a few test characters of that script.
• Then weight. It is the first of Thin, Hairline, ExtraLight, UltraLight, Light, Regular, Normal (written Regular), Medium, DemiBold, SemiBold, Bold, ExtraBold, UltraBold, Black, ExtraBlack and Heavy found in the lower-cased PostScript name. If none is found, the subfamily is used when it is one of those words, and otherwise Regular. “ Italic“ is appended when the PostScript name contains “italic”. Because “bold” is tested before “extrabold”, an ExtraBold font is labelled Bold.
• A font with no names gets a random postScriptName and fullName. One with no PostScript name uses its uniqueID.
• With the “auto tag” font preference, which is on by default, the weight is also pushed onto tags.
• Fonts opentype.js can’t parse (collections, woff2) go through a second parser, Typr, which writes a different fixed set of keys, every one with only an en value.
• WOFF 2 in Eagle 4.0 (observed in code, result inferred): woff2 is routed to the font handler, but neither the bundled opentype.js 0.11 nor its Typr build has a WOFF 2 reader (neither looks for the wOF2 signature). Both parses are inferred to fail, so a woff2 item gets no fontMetas and no weight tag.

IPTC keywords (observed)

• The preference general.IPTC is off by default. When it is on, Eagle reads keywords from files whose extension is exactly jpg. A .jpeg file is not read.
• It looks only at the first APP13 segment, in the “Photoshop 3.0” resource 0x0404, and takes IIM dataset 25 (keywords) from it. XMP is never read.
• A keyword field over 200 characters is skipped. The rest are split on ;.
• The parts are appended to the caller’s tags, and the whole list is de-duplicated (first occurrence wins).
• This happens before the copy, so the keyword tags come before the font weight tag.

Duplicates (observed)

Eagle stores no content hash in item JSON and never hashes file bytes. Its duplicate check (getHashID) builds a key from metadata alone:

• svg, tif, tiff and trashed items are skipped.
• Images without a palette fall back to size, width, height and extension.

The key is used when files are imported (seen in file-uploaded, isDuplicateImage and the duplicateModal directive):

• Each imported item whose key matches an item not in the Trash has the first 4,096,000 bytes of both files compared. When they are equal the new item, already written to the library, is held back from the list. The key alone (bmp, tga, txt and formats Eagle can’t preview get an empty key) never counts.
• When the upload queue has finished, the Duplicate File Alert opens. It shows the existing item (“Existing”, with its first folder or Uncategorized) beside the new one, two radio choices, Use existing file (the default) and Keep both, an Apply all (N) box when more than one file is held, and an Import button. The close button or Esc is Don’t Import. ⌘↩ and ⌘Esc answer for every file. A click outside does nothing.
• Use existing file: the new item is deleted for good. Each of its folders the existing item isn’t in is added to it, with that folder’s auto-tags; folders and tags are de-duplicated, and the existing item’s modificationTime becomes the new item’s, so it sorts as just added. The new item’s own tags and notes are not carried over.
• Keep both: the new item stays.
• Don’t Import: the new item is deleted for good.
• The preference notification.notification.when.repeatImage (Notify me when importing duplicates, under Notification) is on by default and also needs the notification master switch. When either is off, nothing is asked and duplicates are imported as new items.

Folder auto-tags (seen)

A folder’s tags key holds its auto-tags. Eagle’s code calls the list it applies extendTags; it is worked out at run time (getExtendTags) and deleted before metadata.json is written, so it is not a setting.

• The list is the folder’s own tags, then its parent’s, then the grandparent’s and so on to the top level. Only the first copy of each tag is kept, and the result is reversed. A folder with tags [d, e] under [c, b] under [a, b] applies [a, b, c, e, d].
• Importing or pasting files into a folder in Eagle’s window appends the list to the item’s tags and removes repeats. Importing into several folders (the add-from-URLs path) joins each folder’s list in turn.
• Adding items to a folder (the inspector’s folder picker, Add to Folder) appends the tags an item lacks, but only when the item was not already in that folder.
• Dropping items onto a folder appends the missing tags to every dropped item, even one already in the folder.
• Eagle’s API addFromPath and addFromPaths don’t apply auto-tags; addFromURL(s) do.
• There is no preference for any of this.

Timestamps

• btime and mtime are the file’s own times (observed).
• modificationTime is the import time. A batch gives each item Date.now() + index, and a repeated value is incremented, so values within a batch are unique (observed). Later saves do not change it (observed).
• lastModified is the time of the latest metadata.json write, so it is a little later than modificationTime (observed).

mtime.json

• Maps each item id to its lastModified, followed by all, the number of items loaded from images/ (observed). Trashed items are probably included (inferred; not checked against a library with trash).
• It is rewritten about one to two seconds after the write queues drain, not once per item (observed).
• Other Eagle instances watch it to notice new or edited items (inferred from the reader code).

How falcon does it

Library::import_file(path, &ImportOptions) runs the same steps in the same order and returns the new id. ImportOptions holds folders, tags, palette (default true), annotation and url.

• Source times. btime falls back to the mtime when the file system has no birth time. Eagle’s behaviour in that case is unknown.

• Name. Falcon removes control characters and / ? < > \ : * | " %, trims spaces and trailing dots, normalises to NFC, and cuts the name so that <name>_thumbnail.png fits in 255 bytes. The exact length Eagle allows is not known.

• Copy. fs::copy, then the source’s access and modification times are set on the copy. There is no cut mode and no fallback copy.

• Unsupported formats. As in Eagle, import::is_recognized refuses only files with no extension and unfinished browser downloads (.crdownload, .part, .download), with FailKind::Unrecognized, so they appear in the failed-imports list. Every other file imports. Formats falcon can’t draw itself go to QuickLook, and a file nothing can draw is imported with width and height of 0, no thumbnail and no palette. Eagle marks such an item noPreview: true and leaves out width, height and palettes (see Library format); falcon does not write those differences yet.

  Eagle’s “The file format is not supported” dialog (Dialog.NotSupport.Format.*) appears only when something dropped from a browser is neither a file nor a link nor image data (onDropContainer). Two other uses of it, for unknown file types in drops and folder imports, are commented out in Eagle 4.0.0, and those files are imported. falcon only receives file drops, so it has no such dialog.

• Failures. If decoding or encoding fails, the item is kept with no thumbnail and no flags, as Eagle does for a thrown error. If the copy fails, the .info folder is removed and the error is returned. An unknown folder id is rejected before anything is written.

• Link files. A dropped .url (Windows shortcut) file takes its address as the item’s url (weblink::read), unless ImportOptions::url is set. Files over 1 MiB or without an address leave url empty. A .webloc is not in Eagle’s list, so it imports as a plain file with no url.

• Palette. Taken from the decoded thumbnail, so it sees the same WebP artefacts Eagle’s analyser sees. palette: false skips it.

• Timestamps. modificationTime is the later of the current time and the previous import’s value plus 1 ms, tracked on the Library, so it is strictly increasing across calls. lastModified is read after the palette is done.

• mtime.json. Updated and written after every import, not debounced. The entry is set to lastModified, and all becomes the count of loaded items. Existing entries that are missing from the file are left missing.

• Folder auto-tags. With ImportOptions::folder_auto_tags on, commit_import appends the auto-tags of the item’s folders (autotag::auto_tags_for) to its tags, skipping tags it already has, in the same write. It is off by default, as for Eagle’s addFromPath; the app turns it on for every import (drops, ⌘V, the collect window). The list is computed from the folders’ tags by autotag::folder_auto_tags, which follows Eagle’s order exactly; a cached extendTags key in a file is ignored.

• Not done. Library metadata.json is not touched, no backup is taken, and stars and concurrency are not implemented.

Format metadata in falcon

• rawMetas. Falcon reads EXIF with the kamadak-exif crate instead of running dcraw, and prints the values the way dcraw does:
  • camera is the Make tag shortened to a known maker name (NIKON CORPORATION becomes Nikon), followed by the Model with a repeated maker word removed. This is an approximation of dcraw’s table (inferred).
  • timestamp is DateTimeOriginal, or DateTime, read as local time.
  • width and height are not written. EXIF doesn’t hold dcraw’s full sensor size.
  • Readable RAW files: the TIFF-based ones (dng, nef, nrw, cr2, arw, srw, pef, 3fr, erf), plus four with their own containers. crw, mrw and x3f give nothing.
    • orf, rw2: TIFF with another magic number in place of 42 (IIRO, IIRS or MMOR for Olympus, IIU\0 for Panasonic). Falcon reads them as TIFF. The camera tags sit where they do in any TIFF.
    • raf: a FUJIFILMCCD-RAW header with the embedded JPEG preview’s offset and length (big-endian, at bytes 84 and 88). That JPEG’s EXIF holds the camera facts.
    • cr3: an ISO media file (ftyp brand crx ). Inside moov, Canon’s uuid box (85c0b687-820f-11e0-8111-f4ce462b6a48) holds CMT1, a TIFF block with the main IFD (Make, Model, DateTime), and CMT2, a TIFF block whose first IFD holds the EXIF tags (exposure, f-number, ISO, DateTimeOriginal, focal length). Falcon reads both.
    • All four produce the same rawMetas keys and formats as the TIFF-based files.
    • Eagle’s dcraw build is inferred to read orf, rw2 and raf, which classic dcraw supports. Classic dcraw predates CR3, so Eagle is inferred to store no rawMetas for cr3 files, where falcon does.
  • ImportOptions::camera_metadata_all_photos (off by default) also stores rawMetas for jpg, jpeg, tif, tiff, heic, heif, png and webp. Eagle never does this. It lets the camera filter work on ordinary photos.
• duration.
  • Audio is read with falcon_library::audio: the length the container gives, after trimming encoder priming (MP3 gapless headers, the MP4 edit list or iTunSMPB, the Opus pre-skip), or by adding up packet durations when the header has no count. Raw AAC is counted frame by frame. A file that doesn’t decode gets no duration. Only Eagle’s six audio formats get one.
  • mp4, mov, m4v, 3gp and f4v are read from the mvhd box (duration ÷ timescale).
  • Other video formats are read through FFmpeg when it is installed (see Video playback), then fall back to Spotlight (mdls), which knows nothing about files in temporary folders.
  • Values can differ slightly from a browser’s, for example around MP3 encoder padding.
• Video sizes. resolutionWidth and resolutionHeight copy the item’s width and height.
• bpm. tempo::bpm(path, ext) estimates the tempo with falcon’s own method rather than Eagle’s beat tracker, over the same opening stretch (tempo::analysed_seconds):
  • The audio is decoded with falcon_library::audio and mixed to mono. A loudness-rise envelope is built at about 100 frames a second: the log RMS over two hops, its positive differences, lightly smoothed, with the mean removed.
  • The envelope’s autocorrelation is scored for every tempo from 60 to 200 BPM in 0.01 steps. Each score averages the autocorrelation at 1 to 4 beat periods, read between lags by cubic interpolation, and is weighted by a gentle preference for tempos near 120 (one octave wide). The best score wins, rounded to three decimals, and is written right after duration, whole values without a fraction.
  • Nothing is written when the file is silent, too short (under about two seconds), has no clear rises (a steady tone), or no beat stands out (hiss).
  • Checked on generated clicks at 60, 75, 90, 120, 140 and 174 BPM, and on a drum loop over a drone, all within 1 BPM. Clicks at 200 read as 100, an octave down, because the preference for 120 breaks the tie. Eagle’s tracker can also land on a different octave, and values on real music will differ from Eagle’s.
  • Refresh Thumbnail recomputes bpm for audio items, as Eagle’s refresh does (generated.bpm replaces the item’s value, seen in app.bundle.js). An existing key keeps its place in the record; when no beat is found the key is removed, as Eagle’s undefined drops it on write. Refreshing an item Eagle analysed replaces Eagle’s tempo with falcon’s estimate, which can differ.
• fontMetas.
  • Read with ttf-parser (ttf, otf, the first face of a ttc) after falcon’s own WOFF 1 and WOFF 2 unpackers (fontmeta::sfnt).
  • WOFF 2 goes further than Eagle: falcon writes the same opentype.js-shaped fontMetas (and weight tag) as for the plain font. The Brotli stream is decoded with brotli-decompressor, and the tables are rebuilt into an sfnt. Tables stored with a WOFF 2 transform (the packed glyf and loca, and a transformed hmtx) are left out, since names, maxp and cmap are all metadata needs. WOFF 2 collections are not read.
  • A TrueType woff2 with packed glyphs therefore has no outlines for the 600×600 specimen. Its thumbnail falls back to QuickLook. CFF-flavoured woff2 and woff2 files with plain glyf get the specimen.
  • Language codes cover the common Windows and Mac Roman languages. Records in other languages or Mac encodings are skipped, where opentype.js would decode them.
  • Collections get the opentype.js shape, not Typr’s.
  • Eagle’s MD5 fallback for fonts with a family name but no English PostScript name is not reproduced.
  • ImportOptions::font_weight_tag (default true, as in Eagle) adds the weight tag. The app sets it from the Preferences switch in the Preview pane.

Duplicates in falcon

The duplicates module compares file contents instead of copying Eagle’s metadata key, and writes nothing to the library.

• Exact copies. find_exact_duplicates groups items, trash excluded, whose originals hash to the same BLAKE3 digest. Only files that share their size with another file are hashed.
• Near copies. find_near_duplicates(lib, threshold) takes a 64-bit perceptual hash of each item’s thumbnail, or of the original for small images shown without one. The hash is a 32×32 grey DCT, keeping the 8×8 lowest frequencies, each compared with their median. Items within threshold bits are grouped, transitively. About 10 suits resized or recompressed copies.
• Cache. The _cached variants take a HashCache, keyed by item id and invalidated when the original’s size or mtime changes. HashCache::save and load keep it as JSON wherever the caller likes.
• Results. Groups list item ids in library order.

The duplicate check on import in falcon

import_check holds the library side. Library::duplicate_candidates(size, ext) lists items not in the Trash with the same size and extension (no file is read), and import_check::same_file compares a staged copy with them by BLAKE3 hash of the whole file, which is at least as strict as Eagle’s 4 MB prefix compare. svg, tif, tiff, bmp, tga, txt and files without an extension are not checked. Staged::original gives the staged copy’s path. Library::use_existing_for_import(existing, folders) is Use existing file: the item joins each folder it isn’t in, with the folder’s auto-tags, and its modificationTime becomes the import time. Unlike Eagle, falcon checks before committing, so a duplicate is never written to the library and nothing has to be deleted afterwards. The app’s side (holding duplicates and asking) is described in The desktop app.

Keywords in falcon

ImportOptions::keywords_as_tags is off by default, as in Eagle. When it is on, the keywords module reads:

• jpg and jpeg: the IPTC block in APP13, parsed as proper IIM records (record 2, dataset 25), and the XMP packet in APP1.
• png: the XMP packet in the iTXt chunk XML:com.adobe.xmp, compressed or not.
• tif and tiff: the IPTC (tag 33723) and XMP (tag 700) entries of the first IFD.

IPTC keywords come first, then the XMP dc:subject items. Eagle’s 200-character limit and ; split apply to both. Falcon also drops empty parts, where Eagle would keep an empty tag. Reading .jpeg, XMP, PNG and TIFF goes beyond what Eagle does.

Screenshots

What Eagle does (seen in its shipped source)

A screenshot is captured to a temporary PNG, converted to the format and quality in Preferences ▸ Screenshot (screencapture.format, screencapture.quality), and halved when screencapture.useRetina is off on a scale-2 screen. The item is named “Screenshot - YYYY-MM-DD HH.mm.ss”. It gets the tag “Screenshot” when it has no tags and screencapture.autoTagging.enable is on, and is copied to the clipboard when screencapture.autoWriteClipboard is on. An area or window screenshot opens the collect window first when general.showCaptureCollectModal is on, and the item is saved into the folders chosen there. Otherwise, and always for a full-screen screenshot, it is imported into the library without a folder.

How falcon does it

crates/falcon-app/src/capture.rs makes the file and app/system.rs hands it to the import (see Screen capture in the app chapter).

• Name. “Screenshot - YYYY-MM-DD HH.mm.ss” in local time, passed as ImportOptions::name. The staged file has the same name, with “ 2“, “ 3“ and so on added if two shots share a second, but the item keeps the name above.
• Tag. “Screenshot” is put in ImportOptions::tags unless Preferences ▸ Screenshot turns tagging off. falcon adds it through the same tag helper the collect window uses, so it never doubles a tag typed there. (Eagle adds it only when the item has no tags; a screenshot has none at this point, so the result is the same.)
• Format and size. The PNG from screencapture is converted with export::convert_bytes to PNG, JPG or WebP at quality 90, 80 or 70. A PNG at full size is only renamed. When “Keep full Retina resolution (@2x)” is off and the screen’s scale is 1.5 or more (Eagle checks for exactly 2), the longer side is halved first.
• Where it goes. The library root with no folders, so folder auto-tags have nothing to add. With “Choose where each screenshot is saved” on, an area or window screenshot waits in the collect window, and Save imports it into the folders picked there with the name and tags shown there. A full-screen screenshot never waits.
• Temp files. The file is written to falcon-paste in the system temp folder. The import deletes it once it has copied it into the library, and Discard in the collect window deletes it. A cancelled capture leaves no file, a failed conversion removes the raw PNG, and a screenshot that arrives after the library closed is deleted.
• Same pipeline. It is an ordinary background import: the duplicate check asks what to do when the picture is already in the library, and a failure goes to the failed-imports list. A batch that held only screenshots, imported straight in or saved from the collect window, does not post “Import finished”.

Importing folders

What Eagle does (observed in app.bundle.js)

Where a folder from Finder is dropped decides what happens:

uploadFolderToSidebar walks the folder (getFolderList), then creates an Eagle folder named after the directory, with one child folder per subdirectory, children sorted by name with numbers compared by value. The new folders get no icon, tags or description. Each file is imported into the folder that mirrors its directory, and the new top folder is opened.

File ▸ Import Folders (importFolders) opens a dialog that picks several folders and sends each through uploadFolderToSidebar at the top level. The Import Folders button on an empty folder’s page passes that folder as the parent instead, and the one on the empty All page passes none. A picked .library is opened instead of imported, but only when it is the only folder picked; otherwise it is skipped. Eagle has no Import Files menu item.

Limits (uploadFolderToSidebar, getFolderList, treeDepth): the walked folder counts as level 1 and each level of subfolders adds one. A folder 15 or more levels deep, or with 100,000 or more files, is refused with a notice and nothing is imported. A folder with 2,000 or more files asks for confirmation first (“contains N items”). Eagle’s count leaves out the files directly inside the dropped folder, counting only those in its subfolders (observed in treeDepth). The grid drop has no limits. Only the Import Folders dialog skips Pixave libraries (.pxvlibrary); a sidebar drop would walk one. Inside folders, junk files (.DS_Store, Thumbs.db and the like) are skipped, and Keynote, Pixelmator and MindNode packages (.key, .pxd, .mindnode) count as files rather than folders to walk into.

How falcon does it

folder_import::walk(dir) reads a directory into a Tree (files and subfolders in natural name order). Hidden files (names starting with a dot) and junk (Thumbs.db, Desktop.ini, Icon\r and the like) are skipped, the three package types count as files, and symbolic links to folders are not followed, so a link cycle can’t loop. folder_import::plan(&tree, parent, new_id) maps the tree to NewFolders (parents first, siblings in order) and (file, folder id) pairs, and Library::create_folders adds the folders in one metadata.json write. Folder names are the directory names as the file system gives them, as in Eagle. Tree::stats() counts levels and files and folder_import::verdict applies Eagle’s limits (MAX_DEPTH 15, MAX_FILES 100,000, WARN_FILES 2,000). falcon counts every file, including those directly in the dropped folder, so its count can be a little higher than Eagle’s.

The app follows Eagle’s three drop targets. Because macOS sends no mouse moves while a drag from another app is over the window, the drop position is read from the system mouse location (drop_pos.rs) and compared with the sidebar’s rect and visible folder rows from the last frame. Dropping only files on the empty part of the sidebar shows a hint instead of doing nothing silently. Each folder imported with its tree is checked against the limits on its own: a refused folder gets a notice, and a large one waits for Import or Cancel in a dialog (one dialog per folder, the others still import). Pixave libraries are skipped by every folder import, the grid drop included, with a message. The grid drop walks folders with the same walk as the tree import, so it skips junk and can’t loop through a folder link; it has no size limits, as in Eagle. A .library among the dropped paths is opened wherever it lands. Import Folders… (in the library switcher menu, and on the empty All and folder pages, as in Eagle) runs the same import from an rfd folder dialog that picks several folders; App::import_folders_dialog() is the entry point for a future File menu. Import Files…, next to it, picks files and imports them into the open folder like a grid drop; it is falcon’s own. Both dialogs open once the frame is done, after the library lock is released. A package can’t be imported by falcon yet (it isn’t a regular file), so it is reported as a failed import.

Importing links

File ▸ Import Links… and the New… menu’s Import Links… (file.import.links, no default shortcut) open a box titled Batch Import Links with a text area for one address per line, Cancel and Import. If the clipboard text starts with http, its valid lines are put in the box. Import checks every line against Eagle’s rule (http:// or https://, then at least two characters that start with something other than space, /, $, ., ? or #, and no spaces); if any line fails, the box stays open and lists the lines it refused under “Invalid link format”. Blank lines are skipped and repeated addresses are imported once (link_import.rs, where the rules are tested).

Each address is then fetched, four at a time, with a 10 second limit. The request goes only to that address and carries no user agent, cookies, referrer or other identifying header. If the first bytes of the response are an image (sniff: PNG, JPEG, GIF, WebP, TIFF, BMP, ICO, AVIF/HEIC/HEIF and SVG), or failing that the server answers with an image type, the image is downloaded and imported as a file with the address as its source and the extension of what the bytes are, so a missing, application/octet-stream or wrongly labelled text/html type does not turn an image into a bookmark; for anything else, an unreachable server included, a .url bookmark is imported, as in Eagle, named after the page’s <title> (the first 256 KiB are read) or the host when there is none. Items go into the open folder, with the address as their URL and no tags, through the usual import queue, so progress, the failed-imports list and the duplicate check apply.

The bookmark’s thumbnail

A bookmark made here gets a screenshot of its page as its thumbnail, as in Eagle, once the import has finished (the import itself skips QuickLook for .url, which has no generator and would wait out its 30 second limit for each bookmark); until then, and if no picture can be taken, its card keeps the plain icon. page_shot/ holds the rules and page_shot/webkit.rs the WebKit side; app/page_shots.rs connects them to the app. A queue on the UI thread loads one address at a time in a web view of Eagle’s page size, 1440 × 900, in a borderless window placed off every display. The page has 20 seconds to finish loading, then 2.5 seconds to settle (Eagle’s wait), then WebKit has 10 seconds to hand over the picture. A worker scales it to the usual thumbnail size, takes the palette and writes <name>_thumbnail.png through Library::set_page_thumbnail, and the card is drawn again. The item’s width and height become 1440 and 900. A page that fails or runs out of time is not tried again unless you ask.

Only two things queue a page: Import Links, for the bookmarks it just made (including one kept from the duplicates dialog), and Refresh Thumbnail, for the bookmarks selected. A .url file dropped in or picked up by Auto-Import is left with its plain icon until you refresh it, so a file nobody looked at never causes a page load. Refresh Thumbnail keeps a custom thumbnail, as for other items. When a refresh gets no picture, the bookmark keeps the thumbnail it had and a message says how many pages could not be drawn. An item whose address has changed since it was queued is skipped, and a library that closes drops its pages.

What the page can do is limited:

• Only http and https addresses are queued. A page navigating to anything else, a redirect to file: included, is refused; a frame may also use about:, data: and blob:.
• Each page gets a new non-persistent WKWebsiteDataStore, so nothing is written to disk or shared between pages.
• A content rule list blocks every load from another site than the page’s, and strips cookies from every request. A page that keeps its styles on a CDN therefore draws without them. Following a redirect to another site still works, since that site then is the page.
• Requests carry WebKit’s default headers and nothing of falcon’s.
• There is no UI delegate, so JavaScript dialogs are answered by WebKit and new windows are refused. Media waits for a user gesture that never comes, so nothing plays.
• At most one page is open at a time, and its web view and window go when it ends.

The queue only ever writes to the item’s own .info folder. The compiled rule list goes through a temporary folder that is removed as soon as it has compiled.

tests/page_shot.rs runs the queue against real WebKit on the main thread, with no Dock icon and nothing on screen, using a page served on a free local port. It checks the picture’s shape and colour, that first-party loads arrive and third-party ones don’t, that no cookie is sent, that dialogs and window.open neither hang nor open anything, that a redirect to a file fails and that a page that never answers times out once. It says it skipped when there is no window server session or WebKit can’t load a local page.

Failed imports

What Eagle does (observed in index.html, app.bundle.js and background.js)

A file that fails in processImage (no extension, empty, a failed copy and so on) is reported as an ADD_ERROR with the error’s message as the reason and added to errorList. The list survives later imports until it is cleared. While it has entries, a toast at the top centre of the window reads “N files failed to import. Click here for details.” Clicking it opens the error modal; its × asks to clear the list. The modal is a table of Name, Source (the file’s path; clicking it reveals the file) and Error Description, with a remove button per row, and four buttons: Clear All (after a confirmation that it can’t be undone), Copy to Clipboard (the files’ paths, put on the clipboard as files), Retry All (every file is imported again with its folders and tags, the list empties and the modal closes) and Close.

How falcon does it

import::Failure::new(path, &error) classifies an error from stage, check_folders or commit_import into a FailKind (missing, not a regular file, empty, format not recognised, unreadable, not enough disk space, staging copy failed, library write failed, unknown folder, other) and keeps the full error text as detail. FailKind::describe gives the reason the app shows. The app’s import thread records a Failure with the ImportOptions used for each file that fails; the list is kept per library until cleared. The “Added N, M failed” message still flashes when a batch ends, and a toast under the toolbar stays while the list has entries, with Eagle’s click and × behaviour. The panel lists the file name, its folder (click to show the file in Finder), the reason (the full error on hover) and per row a Retry button, a Reveal button (disabled once the file is gone) and a remove button, with Clear All (confirmed), Copy to Clipboard (the files, ready to paste in Finder), Retry All (with each file’s own folders and tags) and Close. Eagle has only Retry All and the click on the source; the per-row Retry (the file goes back through the same import with the folders and tags it had, its row leaves the list and returns if it fails again) and Reveal buttons are falcon’s addition.

Auto-import

What Eagle does (seen in js/auto-import/auto-import.js, background.js, preferences.js and my_modules/is-network-drive)

With Preferences ▸ Auto-Import on and a folder chosen (autoImport.enable, autoImport.path, off and empty by default), Eagle watches <chosen>/<library name> (the library’s folder name without .library), making that folder if it is missing, so one chosen folder serves every library. Watching starts when a library loads and when the setting or folder changes, and stops when the library closes or the setting goes off. If the chosen folder no longer exists, an error dialog says so and nothing is watched; the preferences window also forgets such a folder and turns auto-import off. Choosing a folder on a network drive is refused with a warning: the drive check asks for the file system type and refuses smbfs, afpfs and nfs, and smb:// paths.

fs.watch on the folder (debounced by 500 ms), and one pass 2.5 s after watching starts, list the folder. Each entry is skipped when its name contains .tmp anywhere, when it is a folder, when it has no extension or is a .url file, when its format isn’t one Eagle supports (or a plugin thumbnails), or when it is 1,000 bytes or smaller (SVGs: 1 byte or smaller). A file being handled is locked by name. Eagle then checks it every 500 ms until its mtime has stayed the same for six checks in a row (about three seconds), so a copy in progress is waited for, and imports it like a dropped file: into no folder, with no tags, its name without % and emoji. Once the item is added (with or without a thumbnail), the file is deleted from the watched folder. If any files were found, a notice (“N files will start to import”) follows 1.5 s later, when notifications are on and notification.notification.when.autoImport is on (the default).

How falcon does it

crates/falcon-app/src/auto_import.rs holds the rules and the watcher; the pane is prefs::auto_import and the app side App::auto_import_tick in app/import.rs; the FSEvents glue is crates/falcon-app/src/fsevents.rs.

• The same settings and defaults, the same <chosen>/<library> folder. Eagle watches the folder of the library its window shows; falcon, which can have several libraries open, watches the folder of every open library at once, one watcher each (AutoImport::watchers, by library root), and imports into that library whether it is shown or not. A library in the background imports quietly (no notice); its progress and any duplicate question show when it is brought forward. A watcher starts when its library opens with auto-import on and stops when the library closes or the setting is turned off. Watchers never start under the test harness.
• A chosen folder that is gone or on a network volume is refused when picked, and, if it happens later, auto-import pauses with a notice (once, until the preferences change). falcon asks macOS whether the volume is local (NSURLVolumeIsLocalKey), which refuses SMB, AFP and NFS as Eagle does and also WebDAV and other remote file systems.
• falcon doesn’t make <chosen>/<library> by itself; the pane says when it is missing and its Make It button makes it.
• Deleting imported files is a preference, “Delete files after importing them” (Prefs::auto_import_delete), off by default. Eagle has no such setting and always deletes. The pane shows a red warning line while it is on: “Files in the watched folder are moved to the Trash once they are in the library.”
• With it on, a file is removed only after its import committed: the item exists in the library and its original file is in place inside the library. Nothing is removed when the import failed, when the file was held for the duplicate dialog (the dialog still needs it, so it stays in the folder and is remembered), when the file is not a regular file directly inside the watched folder (<chosen>/<library name>, compared after resolving links; a link is never followed), or when it has changed (size or modification time) since it was handed to the import. A file moved to the Trash is forgotten from the remembered list, so the same file dropped in again later imports again, through the duplicate check.
• falcon moves the file to the Trash (NSFileManager trashItemAtURL:resultingItemURL:error:) instead of unlinking it, so a mistake can be undone from the Trash. Eagle deletes the file. If moving it to the Trash fails, the file stays and is remembered (so it isn’t imported again in a loop); the failure is written to the error log, not shown as an import failure.
• With the preference off, files stay in place and falcon remembers each file it handed over (path, size and mtime, the latest 5,000, saved with the app state) and doesn’t import it again while it stays unchanged, across launches too. A file changed in place, or replaced with a different one, is imported again.
• The decision logic (auto_import::may_remove, after_import and Removal::finish) is unit tested on temp folders with the deletion injected: a committed import removes the file; a failed or held import, deleting off, a file outside the watched folder or changed since, and a Trash failure all keep it.
• Eagle uses fs.watch with a half-second debounce. falcon listens to FSEvents through CoreServices (FSEventStreamCreate on a dispatch queue of its own, half a second of latency, file-level events) on the chosen folder, which exists, rather than on <chosen>/<library>, which may not yet; any change there makes the watcher list its library’s folder. If the stream can’t start, the watcher falls back to listing the folder every two seconds (and writes so to the error log), as it also does if the stream ends. A file is imported once its size and mtime have stayed the same for three seconds (Settle); while files wait to settle, the folder is listed again every half second, since a file that stops changing sends no event. Tests inject the events (Watcher::start_with with Wake::Events) on temporary folders and never start a stream; one ignored test (fsevents::tests, run by hand with --ignored) starts a real stream on a temporary folder.
• The skip rules are Eagle’s (auto_import::skip): .tmp anywhere in the name, folders, no extension, .url, 1,000 bytes or smaller (SVGs: empty). falcon also skips hidden files (.DS_Store, ._ files) and unfinished browser downloads, as its drops do, and imports any other format, as a drop does, where Eagle takes only its supported formats.
• The files of each pass go through the usual background import into the library’s root with no folders or tags, so the duplicate check, IPTC keywords, font style tags and the failed-imports list apply. Names are cleaned as for any import (forbidden characters); % and emoji are kept.
• With notices on and “Say when files from the auto-import folder start importing” on (both default), each pass shows “Importing N files from the auto-import folder”.

Progress bar

A bar under the toolbar shows a running import: “Importing 3 of 10 · About 20 s left · name.jpg”. The time left is a straight-line guess from how long the finished items took (progress_eta.rs). It appears once one item is done and two seconds have passed, rounds seconds to the nearest five above ten, and then counts in minutes, or hours and minutes. The bar repaints once a second, so the guess keeps moving while a large file is still being read.

Dock progress

While the background import queue runs (the one the sidebar’s task status shows as Processing or Paused), the Dock icon carries a progress bar along its bottom edge, the share of files finished, as Eagle’s setProgressBar does. Like Eagle, the bar goes away once the import is 97% done, and it is cleared when the queue empties or the library closes. The progress modal (ui/dialogs/progress.rs) drives the same tile through its own slot: while the modal is shown it wins, and when it ends an import still running takes the tile back. dock_progress::set_import(Some((done, total))) is the import’s slot; the combining rule is the pure dock_progress::combine, and the tile is only redrawn when the combined value changes.

Thumbnails

What Eagle does

Every claim is from the renderer code in app/js/thumbs/ and app/js/utils/compress.js.

Whether an item gets a thumbnail

• For png, jpg, bmp and jxl, noThumbnail is true when width and height are at most 960 and the file is at most 15,000,000 bytes (observed). The original is then displayed directly and no thumbnail file is kept.
• A png of at most 960 px on both sides but over 1 MiB still gets a thumbnail (observed).
• webp and animated avif have their own checks (observed that they exist; not read). Falcon assumes the same rule for webp and gif (inferred).
• SVG always renders a WebP, which is used for the palette. Under 100,000 bytes, removeThumbnail and noThumbnail are both set and the file is deleted after the palette is computed. At 100,000 bytes or more the thumbnail stays and neither flag is written. A render error sets noThumbnail only (observed).
• The flags are absent on items that simply have a thumbnail (observed in the fixture).

Size

• The limit is 320 for ordinary images, 480 for documents, design files and 3D formats, and 512 for ico and icns (observed).
• Nothing is resized unless the longer side is over the limit (observed).
• Then the short side becomes the limit. For landscape (w > h) the height is the limit and the width is floor(limit * w / h). Otherwise the width is the limit and the height is floor(limit * h / w) (observed). So 2000x1000 becomes 640x320, and 1000x200 becomes 1600x320, which is an upscale of the short side. This looks like an accident, not intent (inferred).
• Large sources are halved on a canvas until within 1.5x of the target, with high-quality smoothing, then drawn at the target size (observed).

Encoding

• Lossy WebP at quality 0.75, written to <name>_thumbnail.png. The bytes are WebP despite the name (observed).
• If a side exceeds 16383 px, JPEG at 0.7 is written under the same name (observed).
• All of this is done by Chromium’s image decoder and canvas (observed). The exact output bytes therefore cannot be reproduced.

Audio waveforms (observed)

• An audio item’s thumbnail is its waveform.
• Eagle draws it with wavesurfer.js in an off-screen 280×140 container. It uses colour #0072EF, normalised to the loudest peak, on a transparent background.
• The canvas is saved as PNG and then compressed to WebP like any other thumbnail. Sides are multiplied by the display’s pixel ratio, so Retina renders are probably larger (inferred).
• The item’s width and height are 280 and 140.
• Files longer than an hour only have their first 10 MB loaded.
• No peak data is cached on disk (no waveform or peaks file in the item folder). The player re-decodes the file when it shows one.

Font specimens (observed)

A font’s thumbnail is a 600×600 specimen. The item’s width and height are 600:

• The background is white and the text is #333.
• The font is loaded as a web font, and html2canvas captures the block as JPEG at quality 1. It is then compressed to a 320×320 WebP.
• For Latin fonts there are three lines, ABCDEFG, abcdefg and 0123456, at 90 px with line height 1.35. They sit left-aligned in a 400 px block centred on the canvas.
• Fonts that support Chinese, Japanese or Korean get two lines of sample characters at 100 px (one line at 90 px for Korean), then AaBbCcDd and 01234567 at 82 px, in a 380 px block.
• The script is chosen from fontMetas.support and the languages of postScriptName.
• Missing glyphs fall back to an outline font.

Custom thumbnails (observed)

From the context menu’s “Custom Thumbnail” entries and the background window’s set-custom-thumbnail handler:

• The command is hidden for tif, jpg, png, bmp and webp items, whose file is already their picture. Every other format can have one.
• The file dialog offers jpg, jpeg, png, bmp and webp. A file over 10,000,000 bytes is refused with a warning. “From clipboard” also takes a copied gif file, or saves a copied image as PNG first.
• The chosen file is copied byte for byte to <name>_thumbnail.png. It is not resized or re-encoded, so a custom thumbnail can be a large JPEG under a .png name.
• The item’s width and height become the picture’s size, even for a video or PDF (the HTTP API may pass its own width and height).
• The palette is computed from the new file.
• noThumbnail and noPreview are deleted, and customThumbnail: true is set. Being a new key, it lands at the end of the item. removeThumbnail is left alone.
• Grid cards with a custom thumbnail get a custom-thumbnail CSS class. The viewer and the plugin API use the thumbnail in place of the original for formats Eagle can’t show itself.
• Refresh Thumbnail skips an item whose customThumbnail is set. With several items selected falcon refreshes them on a background thread behind a progress modal with a Cancel button that stops before the next item, as Eagle shows a progress dialog for it. “Reset Thumbnail” (shown only when it is set) deletes the key and then refreshes the thumbnail.

GIF frame thumbnails (observed)

From the GIF player’s “set as thumbnail” command and the background window’s regenerate-gif-thumbnail handler:

• The frame on screen is drawn on a canvas. When its short side is over 480 px it is scaled so the short side is 480; smaller frames are kept at their size.
• The canvas is exported as PNG (toDataURL() with no type) and written to <name>_thumbnail.png, replacing the thumbnail.
• The palette is computed again from that file. Nothing else in the item changes: no customThumbnail, and width, height and noThumbnail are left alone, so Refresh Thumbnail later draws the first frame again.

Falcon’s Library::set_frame_thumbnail(id, &frame) does the same, with thumbnail::frame_thumbnail_size for the size (Catmull-Rom scaling, where Chromium’s canvas scaling may differ by a few levels) and the image crate’s PNG encoder.

Refresh Thumbnail (observed)

The regenerate-thumbnail queue reads the original’s size, birth time and mtime again (size, btime, mtime), then runs the same per-format generator as import, so width, height and the flags are measured again. The palette is then queued the same way as at import. A format Eagle no longer recognises loses its thumbnail, palettes, width and height and gets noPreview: true. When a re-measured image becomes small enough for noThumbnail, the jpg generator sets the flag but does not delete the old thumbnail file (inferred harmless, since Eagle then shows the original).

Crop and rotate (observed)

From the viewer’s rotateImage, cropImage and saveCrop, js/utils/rotateImage.js and my_modules/image-cropper:

• Where. Both are buttons in the viewer’s toolbar. Rotate (⇧R) turns 90° anticlockwise, or clockwise with ⇧ held while clicking. It is offered for jpg, png, webp and bmp. Crop is offered for jpg, png and webp, and is disabled for animated images.
• Rotation is written to the file when the imageRotateMode preference is write, which is the default. The other mode only turns the view.
• JPEG rotation is lossless. Only the EXIF Orientation tag changes, following a table of the eight orientations. The compressed image is untouched.
• Other formats are re-encoded. PNG, WebP and BMP are drawn rotated on a canvas and exported in the same format, at quality 1 for WebP. Animated PNG is refused, and AVIF can’t be written.
• Cropping is always re-encoded. The crop box is cut out on a canvas and exported as PNG, JPEG or WebP, with a quality setting of 100 passed to Eagle’s canvas helper (inferred to mean the best quality). The canvas drops the EXIF block, so a JPEG’s orientation ends up in its pixels. Eagle shows the result and asks before saving.
• Writing. Crop and rotate both overwrite the original in place and keep its name. Crop first copies it to <file>.bk and restores that if the write fails. Rotate writes <file>.tmp and then the file.
• Falcon’s writing. Falcon does not write in place. Rotate, flip and crop put the new bytes in <file>.staged, a copy of the original so that permissions and extended attributes stay, sync it and rename it over the original, keeping the birth time on macOS. There is no .bk.
• Afterwards. Eagle refreshes the thumbnail (see above), which updates size, btime, mtime, width, height, the thumbnail and the palette. The item edit also bumps lastModified; modificationTime stays. Folder covers that show the item are redrawn.
• Undo. There is none. The overwritten pixels are gone.

Flip (observed)

From the viewer’s flipImage and js/utils/flipImage.js:

• Where. The flip button in the viewer’s toolbar mirrors horizontally. With ⇧ held while clicking, it mirrors vertically. For video and audio the same button only mirrors the player. The file is written under the same imageRotateMode: write preference as rotation. Otherwise only the view flips.
• JPEG is lossless. Only the EXIF Orientation tag changes, from lookup tables for horizontal, vertical and both-ways flips: horizontal maps 1↔2, 3↔4, 5↔6, 7↔8, and vertical maps 1↔4, 2↔3, 5↔8, 6↔7. A missing tag counts as 1. The file is written to <file>.tmp first, then over the original.
• PNG, WebP and BMP are re-encoded. The image is loaded, drawn mirrored on a canvas and exported in the same format (quality 1 for WebP, a canvas-to-BMP helper for BMP). AVIF is accepted, then fails because it can’t be written. Other formats are refused. Eagle doesn’t check for animation here (inferred: an APNG would lose its frames).
• Afterwards. Eagle queues regenerate-thumbnail for the item, as rotation does.

Falcon’s Library::flip_item(id, Flip::Horizontal | Flip::Vertical) follows this, with rotation’s semantics (the file is replaced atomically, see Writing above). A JPEG gets transform::flip_orientation, which composes the mirror with the current orientation and reproduces Eagle’s tables. PNG, WebP and BMP are mirrored and re-encoded with the same encoders falcon uses for rotation. Animated PNG and WebP are refused rather than flattened. The item is then refreshed (size, times, dimensions, thumbnail, palette), lastModified is bumped, and the open undo transaction is marked irreversible. transform::can_flip(ext) lists jpg, jpeg, png, webp and bmp.

How falcon does it

The thumbnail module holds the rules as plain functions: plan_raster, plan_svg, target_size, max_side, resize and encode.

• Rules. Falcon applies the flag, size and encoding rules above exactly, including the short-side quirk and the PNG exception.
• Formats. png, jpg/jpeg, webp, gif (first frame), bmp and svg. Other extensions have no thumbnail. The 480 and 512 limits are in the table, but no format that uses them can be decoded yet. The list of 480 extensions is partial.
• Decoding. The image crate. EXIF orientation is applied, so width and height are the displayed size, as with Eagle’s <img> measurement.
• Resizing. One Lanczos3 resize straight to the target, with no halving steps. Pixels differ slightly from Eagle’s.
• Encoding. The webp crate (libwebp) at quality 75, always with an alpha channel. Past 16383 px, image’s JPEG encoder at quality 70.
• SVG. Rendered with resvg, directly at the target size. System fonts are not loaded, so text in an SVG does not render. A small SVG is rendered at its natural size, because its thumbnail only feeds the palette. Width and height are the SVG’s own size, rounded up.
• Text. A .txt file gets no thumbnail, as in Eagle. Its importer (thumbs/txt.js) instead stores the start of the text in the item record under text: the first 32 Ki UTF-16 code units, read as UTF-8. falcon does the same (falcon_library::text::preview, cut at a character boundary), writes the record in Eagle’s key order for text items (no width, height or palettes; text just before lastModified), refreshes text when the editor saves, and reads it again on Refresh Thumbnail. The grid draws the card from it (see The desktop app).
• Reading back. thumbnail::decode sniffs the content, so it reads a thumbnail even though its name ends in .png.
• QuickLook. Formats falcon can’t decode are rendered with qlmanage. A render that takes more than 30 seconds is abandoned, since qlmanage can hang on malformed files.
• Web archives. QuickLook has no MHTML renderer, so an .mhtml file is unpacked (falcon_library::mhtml) into a temporary folder that is removed afterwards, and QuickLook renders its index.html there with the archive’s own styles and images; QuickLook doesn’t fetch anything from the network. The top of the render, cut to 16:10, is the thumbnail, and the item records 1440 × 900, the window Eagle captures pages in. An archive that can’t be unpacked gets no thumbnail.
• Previews inside the file. When QuickLook gives nothing (no generator for the app is installed, or the file is one it can’t read), import uses the preview inside the file, so the item still gets a thumbnail and a size.
  • RAW photos (the extensions in exif::RAW_EXTENSIONS, among them crw, mrw, orf, raf, raw, srw and x3f): the same embedded JPEG the viewer shows (thumbnail::raw_preview), turned upright by the file’s orientation. width and height are the camera’s pixel size, turned the same way. They come from the sizes the file states in its EXIF or TIFF tags (exif::stated_sizes), taking the largest, and only one at least as big as the preview, since a thumbnail IFD states a small size; failing that, from Spotlight; failing that, the preview’s own size. A RAW file with no embedded JPEG (some Minolta MRW files hold only sensor data) gets no thumbnail.
  • Sketch (previews/preview.png), XMind (Thumbnails/thumbnail.png) and Keynote (preview.jpg, QuickLook/Thumbnail.jpg or Data/st-* slide pictures, also under a <name>.key/ folder): read from the file’s zip (zip_preview). Many Keynote files have none: the 2018 sample holds only Index.zip, with .iwa parts and no picture.
  • IDML (zip_preview): a thumbnail* or preview* picture in the zip, else the base64 JPEG in the xmpGImg:image element of META-INF/metadata.xml.
  • Illustrator (ai, ait) saved PDF-compatible: page 1 drawn by PDFKit (falcon_pdf), with the page’s size in points as the item’s size. Otherwise it is read like an EPS.
  • EPS (binary_preview::eps): the TIFF of a DOS EPS binary header, else a %%BeginPreview bitmap, else an Illustrator %AI7_Thumbnail block (a palette, then RLE and palette indexes, accepted only when the pixels come to exactly width times height). An EPS with none of these gets no thumbnail, since falcon has no PostScript interpreter (Ghostscript is AGPL).
  • InDesign (indd, indt; binary_preview::indesign): the base64 JPEG in the XMP packet’s xmpGImg:image, the largest when a file holds several.
  • Blender (binary_preview::blend): the TEST block’s RGBA rows, in plain and gzip files. A zstd-compressed file (Blender 3.0 and later with compression on) gets none, since no zstd decompressor is in the dependency tree.
  • SketchUp (binary_preview::skp): the first PNG in the file at least 64 px on its short side, which comes before the material textures, or the thumbnail entry of a zip.
  • AutoCAD (binary_preview::dwg): the image section the seeker at byte 13 points to, a DIB or a PNG. WMF previews are not read.
  • All of these files are untrusted: reads are bounded (16 MiB for a picture, 1 GiB for a scan, linear in the bytes read), every stated length and offset is checked, pictures decode under size and memory limits, and anything malformed means no thumbnail. The item’s size is the preview’s, except a PDF-compatible Illustrator file’s.
  • The viewer draws the thumbnail from the start for a format QuickLook renders, while QuickLook runs and if it fails (loader::stand_in_job), so an item with a thumbnail never opens to the bare file icon.
  • In the viewer and preview windows, qlmanage runs on one worker of its own in each Loader, so a run can’t hold up anything else. On this kind of Mac it hangs instead of failing for a format with no generator (blend, dwg, indd, skp, sketch, xmind, idml, eps and PostScript AI were seen), while a real generator answers a small file in about 0.3 s. Every job starts on a fast worker, which tries falcon’s own decoders (a PSD’s merged image, a RAW’s preview, ImageIO) and moves the job to the QuickLook worker only if they can’t give a picture. A fast worker takes thumbnail stand-ins (the preview tier) before anything else. The grid’s thumbnails are ordinary fast jobs.
  • Leaving an item drops its queued jobs and kills its running qlmanage, regions included. That isn’t a failure, so coming back asks again. Closing a preview window or a library kills its run too.
  • A run gets 30 seconds, or 5 for the formats in import::embedded_first, which rarely have a generator. A run that runs out marks the format (by its canonical name) for the rest of the session and for every loader: QuickLook isn’t tried on it again, the full tier of its items is the thumbnail at once, and an item with no thumbnail goes straight to the “can’t preview” page. A run that merely fails isn’t remembered, since it costs little and may be about that one file. A PDF-compatible AI still draws sharp zoomed parts through PDFKit after that, and a PSD through its merged image. Import still uses its own 30-second run, as nobody waits on it in the viewer.
• Video through FFmpeg. Video macOS can’t read (mkv, webm, avi, wmv, flv, ts and the rest) is thumbnailed through FFmpeg when it is installed, before QuickLook, and other video falls back to it after QuickLook fails. As Eagle’s mpv fallback does, the picture is taken ten seconds in, or a third of the way through a shorter clip, and written as a 480-wide JPEG to <name>_thumbnail.png; when that picture is black, up to five later ones are tried. See Video playback.
• Audio.
  • waveform::peaks decodes the file with falcon_library::audio (the decoder the player uses; see Audio formats in The desktop app) and returns (min, max) pairs of the mono mix for any number of buckets.
  • waveform::render draws them one column per bucket, normalised and mirrored around the middle.
  • Import draws 280 buckets at 280×140 in #0072EF on transparency, sets width and height to 280 and 140, and stores that as the thumbnail. There is no pixel-ratio scaling.
  • Nothing is cached, as in Eagle. If decoding fails, QuickLook is tried instead.
• Fonts.
  • fontpreview::render loads only the font into a fontdb, lays out the specimen as SVG text and draws it with resvg at 600×600. Import then scales it to 320×320.
  • Baselines follow CSS: half the leading, then the font’s hhea ascent.
  • The layout and sizes are Eagle’s. The CJK sample words are falcon’s own.
  • Missing glyphs are left blank instead of drawn in an outline font.
  • The result is opaque RGB, as Eagle’s JPEG capture is.
  • woff2 is unpacked first. A TrueType woff2 whose glyphs are stored packed (the usual case) has no outlines after unpacking, so it falls back to QuickLook instead of drawing a blank card.
• 3D models.
  • obj, stl, ply, glb, 3mf, fbx, dae, 3ds and ifc are drawn by model3d::raster instead of QuickLook, as Eagle renders models in its own viewer at import.
  • The model is drawn in the viewer’s opening view (Y up, fitted, Eagle’s lighting and default colour) on a transparent 1080×1080 canvas at 2× supersampling. The empty border is cropped and 40 transparent pixels are added on each side.
  • Textures are drawn: glb, obj, fbx, dae and 3ds meshes sample their diffuse picture per pixel, bilinearly in linear light at perspective-correct texture coordinates, times the tint, and pixels under a glTF MASK cutoff are left out. Normal, bump and emissive maps and see-through meshes are drawn too, far meshes first. Pictures are read only from next to or below the model, decoded at most 4096 px a side and 64 MB per model; a missing one leaves the material colour (see Textures in the app).
  • That image is the thumbnail, not scaled down (max_side is 1160 for these formats), and width and height are its size, as in Eagle.
  • A model that can’t be read falls back to QuickLook. IFC is drawn through web-ifc when falcon is built with it, so swept, CSG, boolean and b-spline solids reach the thumbnail with their openings cut; without web-ifc an ifc file with no tessellated geometry falls back to QuickLook.
• Custom thumbnails. Library::set_custom_thumbnail(id, path) follows Eagle: the same format and 10 MB rules, a byte-for-byte copy, width and height from the picture, a new palette, noThumbnail and noPreview removed and customThumbnail: true appended. It also refuses a file it can’t decode. reset_custom_thumbnail removes the key and redraws. thumbnail::has_custom_thumbnail and custom_thumbnail_allowed hold the rules; jpeg and tiff count as jpg and tif.
• Refresh Thumbnail. Library::refresh_thumbnail(id) re-reads size and file times, then redraws with import’s own pipeline and recomputes the palette, or for audio the bpm (see Import). It returns false and changes nothing for an item with a custom thumbnail. The new thumbnail replaces the old file only once it has been drawn, so a failed redraw keeps the old one. Unlike Eagle, a thumbnail that is no longer needed is deleted, because falcon shows a thumbnail file whenever one exists.
• Crop, rotate and flip. In transform: Library::rotate_item(id, quarter_turns) (clockwise; negative is anticlockwise), Library::flip_item(id, Flip) (see Flip above) and Library::crop_item(id, PixelRect), in the image’s displayed pixels.
  • Formats: rotate takes jpg, png, webp and bmp, crop takes jpg, png and webp. GIF, SVG, PDF and the rest are refused, and so are animated PNG and WebP.
  • A JPEG rotation rewrites only the EXIF orientation. An existing tag is changed in place. EXIF without the tag gets a copy of IFD0 with the tag added, appended to the block. A JPEG without EXIF gets a minimal block after its JFIF header. The compressed image data is copied unchanged.
  • Everything else is decoded with the image crate, turned or cut, and encoded again in the same format: PNG, JPEG at quality 100 with no EXIF (as Chromium’s canvas does), BMP, and WebP through libwebp. Eagle’s canvas exports WebP at quality 1, which falcon takes to be lossy quality 100 (inferred); falcon keeps a lossless WebP lossless.
  • The file is replaced atomically through <file>.staged rather than overwritten in place, and its birth time is kept on macOS. Then the item is refreshed as by Refresh Thumbnail and saved through update_item.
  • Undo: falcon’s undo can’t restore pixels, so these edits mark the open undo transaction irreversible, like a permanent delete. In the app that clears the undo history rather than restoring dimensions that no longer match the file.

Colour palettes

Every item’s palettes field lists its dominant colours with each colour’s share of the image:

"palettes": [{"color":[106,147,68],"ratio":45},{"color":[5,67,121],"ratio":31},{"color":[160,181,138],"ratio":2.22}]

Eagle uses these for colour search and for the swatches in the inspector.

What Eagle does

Which image it analyses (observed)

Eagle doesn’t analyse the original file directly. It uses:

• the item’s thumbnail, normally;
• the original file, when the item has noThumbnail but not removeThumbnail (small PNG, JPG, BMP and JXL files);
• a temporary thumbnail for small SVGs (removeThumbnail), deleted once the palette is stored.

The image is drawn onto a canvas at most 360 px wide. It is never enlarged, and the aspect ratio is kept.

Sampling (observed)

Eagle doesn’t count every pixel of larger images. It takes every Nth pixel, with N chosen from the size of the RGBA buffer:

A 320 × 320 thumbnail is 409,600 bytes, so Eagle samples every 10th pixel. Pixels with alpha below 170 are skipped.

Median cut (observed)

The colours come from modified median cut quantization (MMCQ), the algorithm behind the color-thief library. It is not k-means.

1. Histogram. Each sampled pixel is reduced to 5 bits per channel, giving 32 × 32 × 32 bins, and counted.
2. One box. A box is drawn around all the colours that occur.
3. Split by population. The box with the most pixels is cut along its longest side near the pixel median. This repeats until there are 9 boxes (75% of 12), or 5 cuts have been made.
4. Split by population × volume. The boxes are re-ranked by pixel count times box volume, so large sparse regions also get cut, for up to 5 more cuts.
5. Colour of a box. Each box’s colour is the pixel-weighted average of its bins’ centres.

The 5-cut limit on each pass means a palette rarely has more than about 11 colours, even though 12 are requested.

From boxes to ratios (observed)

• ratio = the box’s pixel count divided by the number of sampled pixels × 100, rounded to two decimals.
• A ratio of 5 or more is truncated to a whole number. That is why the example mixes 45 with 2.22, and why the ratios don’t add up to exactly 100.
• Colours below 0.25 are dropped, and the rest are sorted from largest to smallest.
• The top 5 are always kept. The 6th needs a ratio above 0.1, and later ones above 0.3.

A quirk (observed)

The code that finds the starting box tracks each channel’s minimum and maximum with if … else if. A value that lowers the minimum is never also checked against the maximum. For the first pixel, every channel lowers the starting minimum of 31 (unless it is 31 itself), so the first pixel never sets a maximum. An image with a single counted pixel therefore gets an empty box and no palette. For real images this almost never matters.

Refresh Palette (observed)

The “Refresh Palette” menu entry (and /api/item/refreshPalette) sends the items to the colour analyser’s queue:

• The source is the original when the item has noThumbnail, otherwise <name>_thumbnail.png. The removeThumbnail case doesn’t matter here: a small SVG has noThumbnail too, so its SVG file is drawn.
• The analysis is the same as at import, at most 360 px wide.
• Only palettes is assigned on the stored item, so it keeps its place among the keys. processingPalette is a temporary key that is removed again.
• Audio files are skipped (mp3, wav, flac, ogg, aac, m4a).
• Items whose image would exceed 30 megapixels when scaled to 480 px wide are not analysed.

How falcon does it

falcon_library::palette::extract(&DynamicImage) reproduces the whole pipeline: the 360 px analysis image, the sampling step, MMCQ with Eagle’s control flow, and the rounding and filtering rules.

The port keeps the details that affect the output:

• The bounds quirk. It is reproduced exactly.
• Box ordering. Boxes live in a queue that is sorted only when popped, and only if something was pushed since the last sort. Ties keep their insertion order, so the colour order stays the same.
• Number format. Ratios are written as JavaScript would print them, 3 and not 3.0, so the JSON stays byte-identical.

Checked against Eagle

The matches_eagle_on_fixture_thumbnails test recomputes the palette for all 19 fixture items that have a thumbnail. Eagle computed its palettes from those same files.

The quantizer is therefore an exact match. The remaining difference is the resize step. Chromium scales canvases in Skia with fixed-point arithmetic. Falcon uses one bilinear sample per pixel. Of six filters tried, point-sampling filters came closest and area-averaging filters (box, triangle) did worst, which fits Chromium sampling without mipmaps. Matching Skia bit for bit isn’t worth it here.

Refreshing

Library::refresh_palette(id) recomputes palettes with extract, from palette::refresh_source: the original for noThumbnail items (a small SVG is rendered at its own size), otherwise the thumbnail. Audio is skipped and the result is false. Only the palette changes, and the edit goes through update_item like any other. The 30-megapixel check is not applied.

Search and filters

Eagle has no search index. Every search is a linear pass over the items held in memory, and so is falcon’s (falcon_library::search).

Keyword search (observed)

Eagle joins an item’s searchable text into one lower-case string and tests each term as a substring. The text includes:

• the text content of a text item, and the camera (rawMetas.camera), always
• the name
• the extension with a leading dot, such as .png
• the URL, only for queries of at least 2 characters
• the notes
• the text of every comment, region and video comments alike
• for a font, its full name (the zh entry first, else en), and, for queries of at least 3 characters, its whole fontMetas as JSON
• the tags
• the name and description of every folder the item is in

There is no accent folding: e doesn’t match é.

Search Scope (observed)

The caret beside the magnifier in the search box opens the Search Scope menu. It has a checkbox each for Name, Folder Name, Folder Description, Extension, Tags, URL, Comments and Notes, all on by default. An unchecked part is left out of the search text. The text content, camera and font names are not in the menu and are always searched. falcon remembers the choice across launches, shared by every library (SearchScope, kept by crates/falcon-app/src/search_state.rs). search_text_in builds the text for a scope, and search_text uses every part.

Search All

⌥⌘F (Find ▸ Search All) leaves the viewer, opens the All page and focuses the search box, so the search covers the whole library.

The query syntax:

Eagle doesn’t evaluate a real expression tree. It flattens the query into three lists: terms that must all match, OR groups where one member must match, and terms that must not match. So dog || (cat black) means dog OR the literal text cat black. Falcon reproduces this flattening.

If the terms fail, Eagle makes one last attempt: it tests the whole query as a single substring.

Typo tolerance (falcon only)

Eagle has no typo tolerance: an item matches only when the text is in it. falcon’s app can add typo tolerance on top of Eagle’s matching (Query::fuzzy_score) with Preferences ▸ General ▸ Search ▸ “Also find near misses when searching” (Prefs::typo_search). It is on by default, a deliberate falcon extra; turned off, the search box gives Eagle’s exact-substring results. The HTTP API always keeps Eagle’s exact behaviour.

When nothing matches a search or the active filters, the grid says so in the middle (“No Matches”, with a hint to try another keyword or loosen the filters), as Eagle shows its own nothing-found message with a search illustration.

With the preference on:

• An item that matches the way Eagle matches costs 0 edits.
• Otherwise, each AND term, and one member of each OR group, must match the start of some word in the item’s text within a small number of edits. The edits are insertions, deletions, substitutions and swaps of two adjacent letters (optimal string alignment distance).
• Words are runs of letters and digits, so photography_01.jpg has the words photography, 01 and jpg.
• A term may match a whole word, or a word prefix at least as long as the term. So tigr finds tiger, but not tiramisu through tir.
• The edit allowance depends on the term:

• Common Latin accents fold in typo matching, so creme finds crème.
• NOT terms (-bird) stay exact.
• Order: exact matches come first, in the chosen sort order. Typo matches follow, fewest total edits first, and in the chosen sort order within the same count.
• Speed: a word is skipped without computing the distance when the term has more letters missing from the word entirely than its allowance. On 20,000 synthetic items a search takes 6–12 ms in a release build.

Filter bar

The bar under the toolbar shows one chip for each filter that is pinned or on. Eagle’s default pins are Color, Tags, Folders, Shape, Rating and Type. The + button lists every filter the library can use, each with a pin that keeps it in the bar or takes it out, and clicking a name opens that filter. Duration, BPM, Camera and Font are only listed when some item has a value for them. The pins are remembered across launches with the search scope. Chips can be dragged sideways to reorder them (a press starts a drag once the pointer has moved 10 points, so a click still opens the chip); the new order, kept as the full list of filters as Eagle’s eagle.filter.toolbar.orders does, is remembered across launches and is also the order of the + menu.

A filter that is on always shows its chip, pinned or not, and a chip opened from the + menu or a key stays until its menu closes. The code is in crates/falcon-app/src/ui/filter_bar/mod.rs and ui/filter_bar/media.rs.

• Clear appears while any rule is on. It switches every rule off and also releases the Lock, as Eagle’s reset does. The search text stays.
• Clear Filter (⇧⌥⌘F, Find ▸ Clear Filter) does the same as the Clear button.
• Lock appears while a rule or a search is on. Opening another view (a folder, a smart folder, a tag, All, the Trash, going back or forward) switches every filter rule off and empties the search box, unless the Lock is on. Opening the view that is already open changes nothing.
• Filter Sidebar (⌥⇧F) shows the sidebar and focuses its folder filter box.

Find ▸ Open Filter and the keys ⌥F (Folders), ⌥T (Tags), ⌥C (Color), ⌥S (Shape), ⌥R (Rating), ⌥D (Date) and ⌥E (Type) show the filter bar and open one filter’s menu. The Size, Dimensions, Duration, Comment, Notes, URL, Font, BPM and Camera rows exist in the menu and under Preferences, Shortcuts, and have no key.

Filter rules (observed)

Every active rule must pass.

• Tags and folders: each has Any, All and Exact logic. Eagle has an OR-mode quirk: under Any, an item that has an included tag passes even if it also has an excluded tag. The folder filter matches folder ids exactly and doesn’t include subfolders.
• Type: accepts an extension, or a group such as video, audio, font, word, excel or powerpoint.
• Size, width and height: inclusive ranges.
• Rating: any of the selected star values, with 0 meaning unrated.
• Shape: see below.
• Notes, URL and Comment: has a value, has no value, or contains all of the given keywords.

Comment (observed)

The rule reads an item’s region and video comments (comments[].annotation). Has needs at least one comment, None needs no comment, and Keywords needs every keyword, case-insensitively, to occur in one of the comments (not necessarily the same one). Notes and URL use the same three choices over one text.

Size and Dimensions (observed)

• Size takes a minimum and a maximum in KB or MB (1 KB is 1024 bytes, 1 MB 1,048,576 bytes). A bound may have a fraction; it is converted to bytes and truncated to a whole byte.
• Dimensions takes a minimum and a maximum for the width and for the height, in whole pixels (fractions are truncated).
• Each bound is inclusive and an empty bound is open.

Shape (observed)

• The ratios compare floats for equality, so 1366 × 768 is not 16:9 and 1920 × 1080 is.
• In the custom ratio a side left at 0 (unset) lets every item through.
• The ticked shapes are OR-ed, the custom ratio included.
• The menu lists a shape with its count and hides one with no items (unless it is ticked). shape_counts counts as Eagle does: only items with a width that are not audio or fonts, each in exactly one of landscape, portrait, square, panoramic landscape and panoramic portrait, and in at most one of the four ratios.
• Rating and Type hide options with a count of 0 in the same way (unless the option is on).

Tags chip

The menu has the Any, All and Exact choice and a search box. Without a search, tags in a tag group come first, in the order of their first group, then the others, each in plain code-unit order. With a search the tags are ranked by name (see Name ranking below). A sidebar in the menu switches between All Tags, Selected (the included and excluded ones) and each tag group that has tags in the list. Untagged is a row of its own on the All Tags page. Select all, on a group’s page, includes every tag listed there. A click includes a tag and a right-click excludes it. The chip reads the included names, then the excluded ones with a leading minus.

Folders chip

The menu lists the folders that hold items, in tree order and indented by depth, with their counts, and Uncategorized first. A search box ranks them by name and shows them flat. A click includes a folder and a right-click excludes it, Uncategorized included. Excluding Uncategorized is SetFilter::exclude_empty, which drops items that are in no folder under Any, All and Exact alike. Under Any, an item passes when it has an included folder, even if it also has an excluded one, or when excludes are set and it has none of them; with exclude_empty set, an item in no folder counts as excluded. All and Exact need every included folder and none of the excluded ones.

Type filter (observed)

type_included follows Eagle’s order and its early answers:

1. An item whose own extension is included passes.
2. If the video group is included, the answer is final: the item passes only if it is a video. So including both video and audio lets only videos through.
3. A url entry takes bookmarks without a site. The youtube, vimeo and bilibili entries take bookmarks whose medium is that site.
4. If the audio group is included, the answer is final: the item passes only if it is audio.
5. The word, excel and powerpoint groups, then font.

An excluded extension or group, or an excluded url or site, removes an item. The video group holds ts, 3gp, mp4, mov, m4v, webm, mkv, avi and similar; audio holds mp3, wav, flac, ogg, aac and m4a; font holds ttf, otf, ttc, woff and woff2.

The menu lists the extensions present, in code-unit order, then the built-in groups, with counts and a search box. A bookmark with a site counts under the site. Eagle lists the font, video and audio groups but never counts them, so its panel hides them. falcon counts them (type_counts), so they show.

Dates (observed)

Eagle’s panel has two date rules: Date Imported reads modificationTime, and Date Modified reads mtime, falling back to modificationTime when mtime is 0. All times are integer milliseconds. There is no Date Created rule in the panel; btime is only used by smart folders. Falcon adds a Date Created rule (Filter::created, reading btime with the same fallback) for the app; that part is falcon’s own.

Each rule has presets, a calendar range and a month list:

• “Yesterday” is midnight minus exactly 24 hours, so a DST change shifts it by an hour. Eagle’s midnight also keeps the current milliseconds (it calls setHours(0, 0, 0) without the ms argument); falcon uses exact midnight.
• The range holds the local midnights that start the first and last picked days. An item passes when start ≤ time ≤ end + 24 h, so the last day is included whole, plus the exact next midnight. The range is ignored unless both ends are set.
• The presets and the range are OR-ed: any one of them is enough.
• The month list (YYYY/MM keys, local time) is a separate rule. When months are selected, the item’s month must be one of them, in addition to the presets.
• Eagle’s Date Modified range reads the Date Imported range’s values, which looks like a bug. In the app both rules share one picker, so the effect is the same. Falcon gives each rule its own range.

Duration (observed)

• Reads duration, in seconds, which may have a fraction.
• Min and max are entered in seconds, minutes or hours. Each bound is converted to seconds and truncated with parseInt. The test is duration ≥ min and duration ≤ max, both inclusive.
• Any numeric bound, including 0, makes the rule active. Items with no duration then fail.

BPM (observed)

• Reads bpm, the tempo of audio items, which may have a fraction.
• Min and max are each truncated with parseInt. The test is bpm ≥ min and bpm ≤ max, both inclusive.
• Any numeric bound makes the rule active. Items with no bpm, or 0, then fail.
• In saved filters the rule is bpm: {min, max}, with each key present only when set. Dates, duration, camera and font are saved too; see the saved-filters.json table in Library format.

Camera (observed)

• Reads rawMetas.camera, which Eagle only writes for RAW photos (see Import).
• The options are the distinct camera values across all items, sorted by plain JavaScript string comparison, which is case-sensitive.
• Selected cameras are OR-ed. The match is exact and case-sensitive.

Font (observed)

The font rule is not a family picker. It has two choices, activated and deactivated, which test whether Eagle has installed the font:

• When a font is activated, Eagle copies it into ~/Library/Fonts/EagleApp/ on macOS. At startup it lists that folder and records <base name>_<.ext lower-cased> for each file.
• An item’s key is <postScriptName>_.<ext>. The postScriptName is the first language value in fontMetas.postScriptName.
• Activated passes items whose key is in the set, and deactivated passes those whose key isn’t. Items without fontMetas fail both.

How falcon does it

Filter has imported, created and modified (DateFilter), duration (a pair of optional bounds in seconds), bpm (a pair of optional bounds, read from and written to saved filters; search::bpm(item) reads the value), cameras (a set) and font (FontFilter::Off, Activated(keys) or Deactivated(keys)).

• A DateFilter takes an optional Clock (now and the start of today). With none, it reads the system clock and time zone. local_day_start builds range ends from a date picker.
• DurationUnit::to_seconds converts the min and max fields.
• These helpers build the panel’s options: distinct_cameras, month_counts, duration_range, installed_font_keys_in with font_dirs (Eagle’s EagleApp/ and falcon’s Falcon/ under ~/Library/Fonts, the second a deliberate difference), and distinct_font_families (fontMetas.fontFamily, a falcon extra).

The Color filter’s menu opens with a picker: a square where the horizontal position sets saturation and the vertical position sets brightness for the current hue, and a vertical strip beside it that sets the hue. Dragging either one changes the filter colour as it moves, and the hue is kept when the brightness reaches black. Below it are the swatches, then the hex field with a small square showing the current colour, the accuracy slider, the Grayscale only box and Clear.

The swatches are exposed to assistive technology as radio buttons named after their colours (Red, Orange, …, Moss), with their selected state, and a press on one picks the colour as a click does. The picker’s square and strip are named too. The folder colour rows, the inspector’s palette swatches (named by hex) and the welcome flow’s themes are exposed the same way.

A popup takes every pointer click inside it: egui hit-tests by layer, so a click on a swatch or in the gaps between swatches never reaches the grid underneath. AccessKit’s own hit test walks its tree instead, last child first, and egui builds that tree in creation order, so on its own it finds a card drawn later in the frame before the popup above it. crates/falcon-app/src/access_order.rs sorts each tree update by layer order before it leaves the app, and gives a menu or dialog its bounds so a press between its controls stops there. Two windows in the same layer order keep their creation order, as egui does not publish their stacking.

Colour search (observed)

Eagle compares the query colour with the item’s two dominant palette colours, then with any colour marked as the item’s primary colour.

1. Items with no palette, or whose first colour covers less than 25%, never match.
2. An exact RGB match with either of the two colours matches at once.
3. Otherwise both colours are converted to CIELAB. A colour matches when its CIEDE2000 difference is below the accuracy setting (default 20, range 5–40) and its CIE76 difference is below the accuracy plus 50. Each dominant colour is only tested if it covers more than 33%.
4. Failing those, a palette colour marked as primary (marked: true, set with the inspector palette’s Primary Colour toggle) matches when its CIEDE2000 difference is below 30, whatever its share of the image and whatever the accuracy setting. Its CIE76 distance is the sort key. Rule 1 still applies first.

Smart folder colour rules don’t look at the primary colour, and have no white-background branch; see the Smart folders chapter.

Matching items are sorted by CIE76 distance, closest first.

Falcon’s CIEDE2000 implementation is checked against the published reference values from Sharma et al. One of Eagle’s branches, for mostly white backgrounds, can never run as the code is written. Falcon nests it inside the dominant-colour test, which is what it appears to be meant for. That is inferred.

Name ranking (observed)

Eagle’s tag and folder filter searches, and Go to Folder, rank names with a quick-search score (string_score). It is 1 for identical strings and 0 when the letters of the keyword don’t all appear in the name in order. Otherwise it rewards letters that follow each other, letters that start a word and letters whose case matches, plus a bonus for a shared first letter. Lengths and positions count UTF-16 units, as in JavaScript.

rank_names applies it as Eagle does:

• Spaces are dropped from the keyword.
• Both sides are decomposed (NFKD), stripped of combining accents and lower-cased, so e finds é.
• Names that score 0 are dropped, and the rest are ordered best first, with ties keeping their order.

Eagle also scores the pinyin of Chinese names and matches traditional against simplified characters. falcon implements neither.

Sorting (observed)

Eagle’s sortIncrease flag reverses this direction when it is off. The Trash is always sorted by deletion time, newest first.

Saved filters

A saved filter stores the filter’s rules and the search text in saved-filters.json (see Library format). Applying one replaces the whole filter and the search, and refills the fields of the filter menus. The rules falcon reads and writes include:

• comments, under annotation (has, none or keywords)
• the ratio shapes 43, 34, 169 and 916, and the custom ratio as custom with width and height
• excluded Uncategorized, as folder.excludes.NoFolders, next to the excluded folder ids
• tags, folders, type, size, dimensions, rating, notes, URL, colour, dates, duration, BPM, camera and font
• Eagle’s AI searches, image and semantic, which AI Search applies; until it can, they are kept and the filter bar says why (see the App chapter)

Go to Folder

⌘J (Find ▸ Go to Folder…) and a bare J open a switcher near the top of the window. Pressing the key again closes it, and reopening it keeps the last keyword, selected. The code is in crates/falcon-app/src/quick_switch.rs and ui/dialogs/quick_switch.rs.

• Tabs: Folders, Tags, Smart Folders and Items. Tab moves to the next tab and ⇧Tab to the previous one, both wrapping.
• No keyword: the Folders and Smart Folders tabs list the whole tree in order, indented by depth, with the parent’s name muted at the right. The Tags tab lists tags with grouped ones first, then the others, each in plain string order. The Items tab lists every item that is not in the Trash.
• Recents: when there are more than 15 folders (more than 10 smart folders) and some history, up to 10 recently opened ones that still exist come first. They are listed again in the tree below, so they show twice.
• With a keyword: folders, smart folders and tags are ranked by name (see Name ranking) and shown flat. Items are searched with the same search text and query syntax as the search box, with no typo tolerance.
• Keys: ↑ and ↓ move the highlight, Return opens the highlighted row and closes the switcher, Esc closes it, and a click opens a row. A folder or smart folder opens as a view; a tag opens its page; an item opens the first of its folders that exists (else All) with the item selected and scrolled into view.
• History: opening a folder or a smart folder moves it to the front of its list, which keeps the latest 200 and is remembered across launches with the other search settings, shared by every library.

Smart folders

Smart folders live in the library metadata.json as smartFolders. Falcon keeps each entry as raw JSON so it round-trips unchanged, and evaluates it through falcon_library::smart.

Shape (observed in code)

The Assets fixture has no smart folders, so these shapes come from Eagle’s code, not from a real file.

Eagle’s save rebuilds each top-level entry with these keys, in this order. Unset keys are dropped:

{ "id": "…", "icon": "star", "iconColor": "pink", "name": "Red logos", "description": "",
  "modificationTime": 1793000000000,
  "conditions": [ { "rules": [ { "property": "type", "method": "equal", "value": "png" } ],
                    "match": "AND", "boolean": "TRUE" } ],
  "children": [] }

Nested entries aren’t rebuilt. Eagle writes them as they sit in memory, minus newFolderName, editable and $$hashKey. A child made in the dialog is {id, name, conditions, modificationTime, children, parent}. parent is the parent smart folder’s id, and keys set later (icon, iconColor, orderBy, …) follow in the order they were added. Eagle may also write runtime keys such as imageCount or pinyin into nested entries. Falcon doesn’t add those (inferred to be harmless, since Eagle recomputes them on load).

Editing (observed)

• Create: the dialog appends a new smart folder to the top level or to the chosen parent’s children.
• Edit: the dialog replaces name and conditions and stamps modificationTime. It edits the stored conditions in place, so keys it doesn’t touch stay. On opening it adds boolean: "TRUE" to any condition without one.
• Icon and colour: these are separate menu commands. Picking the blank icon or no colour deletes the key.
• Drag onto a smart folder: appends the dragged folders to its children and sets their parent. Dropping a folder onto one of its own descendants is refused.
• Drag between siblings: inserts the folder before or after the target in the target’s list. Eagle tries to delete parent when the target is top-level, but the delete hits the array rather than the folder. The stale key only lingers on nested folders: top-level entries are rebuilt without it on save.
• Delete: removes the folder with its children. Every edit rewrites metadata.json with a fresh top-level modificationTime.

Falcon’s API, all on Library:

Library::smart_folders() returns SmartFolder values with icon, icon_color, description, order_by and sort_increase read out for display.

The dialog (observed)

Eagle’s dialog lists every condition. Each has a row choosing all (AND) or any (OR) of its rules and whether they must be true or false (boolean), then its rules, one per row: property, method, value. The second and later conditions are labelled as AND-ed with the ones above. A new condition is {"rules": [...], "match": "OR", "boolean": "TRUE"} with one rule, name contains "". A new rule is {"property", "method", "value"}; unit follows for file size and duration, and width and height for a custom shape. Changing a rule’s property resets its method and value. Eagle caps both lists at 30, won’t remove a condition’s last rule, and saves an empty text value as it is (such a rule never matches). Picked dates are stored as local midnight.

Falcon’s dialog (smart_dialog_ui, with the rows in organize_ui::smart_conditions_ui) does the same, in its own words: each condition reads “Items must match / must not match all / any of these rules”, with buttons to add and remove conditions and rules. It offers every property the evaluator knows (table above). Dates are typed as YYYY-MM-DD, or picked from a calendar that opens from the button beside each date field (it starts at the date in the field, else today, and a click on a day fills the field), within takes a day count, folders come from a checklist of the library’s folders, tags are comma-separated, and colours have a swatch picker. A value that can’t be stored (a missing number, a bad date or colour) shows a message and disables Save, where Eagle would store whatever the field held. Falcon also needs at least one condition, so the dialog can’t turn a smart folder into a group. Under the rules, at the left of the buttons, a live count says how many items the rules would show (“12 items found”), counting the smart folder’s ancestors’ conditions too, as Eagle’s dialog does. It counts on a worker thread (smart_count.rs, smart::count_draft) once the rules have stayed unchanged for 250 ms, over a snapshot of the library taken when the dialog first counts; while a newer count is pending the old number is dimmed, and rules that can’t be saved show no count.

Saving never loses rules. The draft lives in falcon_library::smart_draft, which keeps the stored JSON next to what the dialog shows:

• Untouched conditions and rules are written back exactly as they were read.
• Edited ones are the stored object with only the changed keys replaced. Key order and keys falcon doesn’t know survive. Unlike Eagle, falcon doesn’t add boolean to a condition that lacks it unless you invert the condition.
• Unsupported rules: a rule with a property falcon doesn’t know, a method that property doesn’t have, a unit other than the ones listed, or a value of the wrong JSON type shows as a read-only “Unsupported rule” row with its JSON. It is saved verbatim until you remove it.
• Date rules keep their stored timestamp when only the method changes between on, before and after. Switching to or from within restarts the value (30 days), as in Eagle.

Smart folder groups (observed in code)

A smart folder group has no flag of its own. Eagle’s “new smart folder group” command (in the + menu next to the smart folder heading) appends a top-level entry with conditions: [] and the grid icon, named “Untitled” in the UI language. It saves at once, then opens the group and starts a rename. The save writes it as {"id", "icon": "grid", "name", "description": "", "modificationTime", "conditions": [], "children": []}. The command only makes top-level groups, but a group can be dragged into another smart folder like any other entry.

Any entry without conditions behaves as a group:

• View: it shows the union of its children’s items. With no children it shows nothing.
• Badge: it shows no count (Eagle’s counter returns 0 for an entry without conditions).
• Children: each child still has to pass its own ancestors’ conditions. A group adds none.

SmartFolder::is_group() is conditions.is_empty(). create_smart_folder_group(None, name) writes the top-level shape above. create_smart_folder_group(Some(parent), name) nests a group in the key order of Eagle’s new-group object, with parent added: id, name, modificationTime, children, conditions, icon, parent (inferred from how Eagle writes nested entries as they sit in memory).

How falcon differs: Eagle’s union checks each child with its plain rule test, which treats a child with no conditions as matching every item. So a group nested in a group would show the whole library in its parent’s view, but only its own children’s items when opened. Falcon uses the second reading in both places: a nested group is the union of its own children.

Evaluation (observed)

• Conditions: all of them must pass. boolean: "FALSE" negates one.
• Rules in a condition: combined by match. AND stops at the first rule that fails and OR at the first that passes; any other value needs every rule to pass. A condition with an empty rules list passes.
• Errors: Eagle’s whole test fails, negated condition or not, when it reaches a rule whose property it doesn’t know, or a condition without rules. Falcon does the same.
• Nesting: a child must also pass every one of its ancestors’ conditions, so it narrows its parent. Moving a child out of its parent stops the narrowing.
• No conditions: a smart folder without conditions is a group and shows the union of its children (see below).

Rules by property. Number rules take value: [a, b], with b used only by between. Date rules take ms timestamps, except within, whose a counts days.

Eagle’s quirks are kept:

• File size units: any unit other than kb is treated as MB.
• Start and end matches: startWith and endWith build a case-insensitive regex from ^ plus the value and the value plus $, without escaping, so the value is a pattern there too.
• Lower-cased patterns: for the lower-cased properties the regex pattern is lower-cased with the text, so \D acts as \d.

How falcon differs

• Regex engine: Eagle runs JavaScript RegExp; falcon runs the Rust fancy-regex crate, which has look-around and backreferences as JavaScript does. \w, \d, \b and case folding are Unicode-aware, where JavaScript without the u flag is ASCII-only, and a pattern whose backtracking runs past falcon’s limit on a text fails on that text. An invalid regex pattern fails the rule in both, but Eagle fails its whole test on an invalid startWith or endWith pattern, where falcon fails only that rule.
• Installed fonts: like Eagle, falcon counts a font as installed when a file named after it is in Eagle’s font folder (~/Library/Fonts/EagleApp, read once per evaluation). Unlike Eagle, it also counts a font in falcon’s own folder (~/Library/Fonts/Falcon), where falcon’s font viewer activates fonts, so a font activated by falcon is installed for falcon’s fontActivated rule and not for Eagle’s. Fonts installed any other way count as not installed in both. There are no such folders on other systems, so there every font is “not installed”.
• The dialog: see above for how falcon’s differs from Eagle’s.

HTTP API

Eagle serves a local JSON API on port 41595 while a library is open. Extensions, scripts and MCP servers use it. Falcon serves the same API from falcon-server, both inside the desktop app and through falcon serve <library>.

Envelope (observed)

A request is served when its Host header is localhost:<port>, 127.0.0.1:<port> or 0.0.0.0:<port>, or when it carries the Developer token as token: in the query string for GET, in the JSON body or the query string for POST. With no token set, which is the default, only the Host check applies, and no token value (not even an empty one) lets a request from another Host in. With a token set, the value must match exactly. A token that is only whitespace counts as no token. Anything else gets 401. Eagle does the same (observed in json-rest-light), with its port hard-coded to 41595. Eagle’s /item, /folder, /smart-folder and playground handlers skip the check entirely; falcon applies it to them too, on purpose.

v1 handlers reject with a string, which lands in data. v2 handlers throw an Error; Eagle’s JSON server puts its text in message and serialises the error object itself as data, which comes out as {} (observed in the bundled json-rest-light module). A v2 handler that returns nothing gives {"status":"success"} with no data, and false gives "data":false. Each route keeps Eagle’s choice between throwing, false and nothing.

Routes

• v1:
  • application/info (also served at /)
  • library/info, history, switch and icon
  • folder/list, listRecent, create, rename, update and unlock
  • preferences/collect/on and off
  • tag/all, list, listRecent and groups
  • item/addFromPath(s), addFromURL(s), update, info, thumbnail, setCustomThumbnail, refreshPalette, refreshThumbnail, moveToTrash and list
• Links: /item, /folder and /smart-folder redirect to eagle:// links (see “Link redirects”).
• Playground: GET /api/v2/playground (see “The playground”).
• v2: every route in the table below.

v2 lists are paginated as {data, total, offset, limit}. limit defaults to 50 (also for 0 or junk) and is capped at 1000; offset defaults to 0.

Eagle’s quirks are kept:

• Paging: in item/list, offset is a page number, and the page is re-sorted newest first after it is cut.
• Ratings: v1 item/update ignores a rating of 0; v2 item/update accepts 0 to 5.

More v1 routes

folder/unlock lasts for the server’s session only. Until it ends, folder/list and folder/listRecent report that folder with isUnLock: true and its children. Nothing is written to the library.

Link redirects

/item?id=<id>, /folder?id=<id> and /smart-folder?id=<id> answer 302 with a Location of eagle://item/<id>, eagle://folder/<id> or eagle://smart-folder/<id>. An unknown id answers 404 with {"error":"File does not exist."}, {"error":"Folder does not exist."} or {"error":"Smart Folder does not exist."}. These paths go through the same auth check as the rest.

The playground

GET /api/v2/playground serves falcon’s own page, not a copy of Eagle’s. It lists the routes, has a form for the parameters of each, a field for the token, and shows the equivalent curl line.

eagle:// links

The app bundle registers the eagle scheme (CFBundleURLTypes in scripts/bundle.sh). The app handles eagle://item/<id>, eagle://folder/<id> and eagle://smart-folder/<id>, both from clicked links and as launch arguments. A clicked link reaches the running app as an Apple “get URL” event, which falcon catches before the event loop starts. An item opens in the viewer inside its first folder, or All when it has none; a folder or smart folder is shown. Ids the shown library doesn’t have are ignored, and links wait while the app is locked. eagle://openFolder/<id>, the form Eagle’s “added to folder” notices link with, opens the folder in the app as a folder link does (Eagle sends it to the same handler). Plugin links are not handled.

The bundle also registers image, video, design, .eaglepack and .library document types, so Finder’s Open With and Dock drops reach falcon. Files are imported into the shown library, a package is imported as a package, and a library is opened. Folders can be dropped on the Dock icon, but falcon does not become any folder’s default app.

The files reach the running app as an Apple “open documents” event, handled in crates/falcon-app/src/open_files.rs and passed to the same import path as a drop (App::import), as Eagle’s open-file handler imports files and opens packages. AppKit installs its own handler for that event while the app finishes launching, so falcon installs its handler when AppKit posts NSApplicationWillFinishLaunchingNotification, which is still before a launch’s own files arrive. A package asks first, showing its size, as Eagle does. With no library open, files other than a library are ignored.

v2 routes (observed)

Read from Eagle 4.0’s app/js/api-server-v2.js (the route table), api-v2-playground-config.js (parameters) and the handlers in app/js/plugin/index.js and plugin/handlers/smart-folder-handlers.js. “Paged” means the reply is wrapped as above. GET takes the query string, POST a JSON body, so array parameters only work through POST.

tagGroup/addTags keeps a tag in its other groups unless removeFromSource is set, in which case it moves.

Smart-folder conditions are checked strictly before anything is saved. The first problem is reported, in Eagle’s words: conditions must be a non-empty array, max 30 conditions, each condition must have non-empty rules array, max 30 rules per condition, match must be "AND" or "OR", boolean must be "TRUE" or "FALSE", then per rule invalid property: …, invalid method '…' for property '…'. Valid methods: …, value is required …, a type message for the value, and the unit or custom-shape width/height requirements.

Updates: Eagle 4.0 has no change feed, cursor or “changed since” route in either API version. The update routes are item/update, folder/update, tag/update, tagGroup/update and smartFolder/update, all served. A client that wants to notice changes has to poll, for example library/info‘s modificationTime (bumped on every library metadata.json write) or the items’ lastModified (inferred; Eagle documents no polling scheme).

Folder update quirk (observed): folder/update compares iconColor and parent with the folder’s current values even when they are left out. A request without iconColor clears the colour, and one without parent moves a subfolder to the root. Falcon does the same, so clients should always send both. A move into the folder itself or its own subtree is skipped silently.

Library switching

library/switch (v1 and v2) opens the given path into the server’s library slot, which the desktop app shares, so the app shows the new library too (see “The desktop app” below). Falcon refuses a path that does not exist (Library does not exist.), and also one that is not a folder ending in .library with a metadata.json (Not an Eagle library., falcon’s own text: Eagle tries to open anything that exists). Opening only reads, so nothing is created or written in the target.

library/history comes from Eagle’s app settings (libraryHistory). In the desktop app, the app hands its recent libraries list to the server with Handle::set_history when the server starts, when the shown library changes and when preferences are applied. falcon serve has no such list, so it reports the libraries it has served since it started, newest first, beginning with the one it was started on. Libraries handed over with set_library count as served.

The desktop app

Eagle has one library open per window, and its API serves that library; library/switch goes through the same code as the library panel (observed in js/api-server.js, which calls the window’s openLibrary). Falcon’s app can keep several libraries open (see Several libraries), and the API follows the one being shown:

• The running server keeps its port. When the shown library changes, the app calls Handle::set_library(Shared), which swaps the library the next request sees and adds it to library/history. Handle::library() returns the one being served. start and serve are unchanged.
• library/switch still replaces the library inside the served slot. The app checks the slot’s root every frame. When it changed, the app puts the library that was there back into the slot (reopened from disk; the server’s drop of it has already written anything pending) and shows the new path in a workspace of its own: an existing one if that library is already open, otherwise a new one with fresh state and no undo history. While tasks run in the shown library the app asks first, with Force Switch and Cancel; on Cancel the served library stays the shown one, although the request already answered true. The path also joins the app’s recent list. If the old library can’t be reopened, the shown workspace becomes the new library and starts over.
• Handle::set_history(paths) replaces the list library/history reports, newest first, dropping duplicates.
• Handle::set_token(token) sets the Developer token; an empty token (or one that is only whitespace) turns the token check off: only the Host check applies, as in Eagle. Handle::set_preferences(value) sets the preferences application/info reports. Handle::take_preferences() returns them when a request changed them since the last call (preferences/collect/on and off), otherwise None. The app calls set_token, set_preferences and set_history together, and polls take_preferences each frame. It keeps showCollectModal changes made over the API; Preferences has no checkbox for it yet.

Developer token

The Developer pane in Preferences holds the API token (Prefs::api_token). It is empty by default, as Eagle’s developer.apiToken is (observed); falcon doesn’t make one on first launch. A token made by an earlier falcon version is kept. While it is empty the pane says “No token. Only requests addressed to localhost are served.” and offers a Generate button, which makes a random UUID, Eagle’s format. With a token set the pane shows it with Copy, which puts it on the clipboard, Regenerate, which makes a new one, and a link of the form http://localhost:<first port>/?token=…. Changes apply on Save or Apply.

The server rule is tested in falcon-server (a unit test of the rule and an end-to-end test), and the default and the keeping of an earlier token in the preferences tests.

How falcon differs, on purpose

• Local only: falcon listens on 127.0.0.1 only.
• Library routes and AI Search only: routes that aren’t about library data (plugins, script injection, window control) are left out, as are bookmarks and batch save.
• AI Search: /api/v2/aiSearch/* answers from falcon’s own AI Search (see the App chapter). isInstalled, isReady, isStarting and isSyncing answer a boolean; getSyncStatus answers isSyncing, done, total and pending; checkServiceHealth answers healthy, status (notInstalled, starting, syncing, ready or error) and error. searchByText takes query or text, searchByBase64 takes base64 or image, searchByItemId takes itemId or id, and each takes limit. They answer the v2 list shape with a score on each item. Before the model is installed or ready they throw and say so, and they do under the falcon command line, which has no model. These shapes are falcon’s reading of the route names; Eagle’s own were not recorded.
• Auth on link and playground paths: falcon checks Host or token on /item, /folder, /smart-folder and the playground; Eagle doesn’t.
• Imports: addFromPath and v2 item/add reply after the import has run, so a returned id exists. Eagle makes up the id, replies, and imports later. A failed single item/add therefore throws in falcon, and a batch lists only the ids that imported.
• Import locking: the add routes (addFromPath(s), addFromURL(s), v2 item/add) read, thumbnail and analyse each source before taking the library lock, and lock only briefly to look up folders and to commit, as the app’s own import does. Downloads for addFromURL(s) also run unlocked. A slow or dataless iCloud source therefore stalls only its own request; the app, which shares the library, keeps drawing.
• Bookmarks: item/add with bookmarkURL throws bookmarks are not supported.
• Add routes, tags: URL routes (addFromURL(s), and v2 item/add with url or base64) put the target folders’ auto-tags first, then the given tags. Path routes add no auto-tags (observed: Eagle’s uploadUrls adds extendTags, while uploadFiles from the API gets no folder). v1 addFromURL(s) also move the given tags to the front of the recent tags, as Eagle’s addHistoryTags does; the path routes and v2 don’t.
• Duplicates: Eagle imports API items and then, with the duplicate notification on, asks in its window. Falcon imports them without asking, because API imports have no dialog yet. This holds for path and URL routes alike.
• Thumbnail routes: item/setCustomThumbnail, refreshPalette and refreshThumbnail finish their work before replying; Eagle queues the work and replies at once. Falcon does it without holding the library lock and writes back only the keys it changed, so edits made meanwhile survive. library/switch and library/icon also read without holding the lock.
• Colours: folder, smart-folder and tag-group colours must be one of Eagle’s eight names; anything else throws. "" or null means the default and removes the key. Eagle stores whatever it is given.
• Tag rename: tag/update also renames the tag in the recent and starred lists, as falcon’s own rename does. Eagle’s API leaves those lists alone.
• Tag groups: names are NFC-normalised and cut to 1024 characters, and tags are de-duplicated, as in falcon’s tag manager.
• Comments: they are written in the order falcon’s model uses (id, region or duration, annotation, lastModified). The addComment reply uses Eagle’s order.
• Smart folders: a top-level entry made through the API is stored in the shape Eagle’s save gives top-level entries, with no empty icon or iconColor. A nested one is stored as the API builds it.
• Library history: see above.
• Several libraries: the app can keep several libraries open; the API serves the one shown, and library/switch opens or focuses a workspace instead of replacing the window’s only library (see above).

Ports

Eagle listens on *:41595. macOS still lets another program bind 127.0.0.1:41595, and that program would then receive every localhost request meant for Eagle. Falcon therefore checks whether a port already answers before binding it. The app always starts at 41596, and falcon serve refuses to start on a port that is already in use.

The desktop app

falcon-app is falcon’s version of Eagle’s main window, built with egui. Its look comes from Eagle itself:

• Colours: dark is sampled from Eagle’s window and its dark-theme stylesheet (style/base/_color.scss). For example, the content area is #17191d, the panels #1f2023 and the accent #3297ff. Light, lightgray, gray, blue and purple are worked out from the stylesheets, and Auto follows the macOS appearance (see Themes below).
• Fonts and icons: SF Pro for text, plus Phosphor Light icons, which are MIT-licensed and close to Eagle’s line icons.
• Measurements: taken from Eagle at 1280 × 800: 240 pt panels, a 48 pt toolbar, 27 pt sidebar rows and 139 pt cards.

Opening libraries

The app and the falcon CLI open and create libraries in any folder, as Eagle does. The HTTP API’s library/switch also opens a library in any folder. The system dialogs behind Open Library…, New Library…, Merge Another Library… and Select Another Path… start in the folder that holds the shown library; with no library open, the system chooses where they start.

The app opens libraries with Library::open_or_restore (see Backups): when a library’s metadata.json can’t be read or parsed, the newest usable backup in its backup/ folder replaces it before the library loads, and a message names the backup used and says the damaged file was kept in backup/. This covers the switcher, Open Library, libraries reopened on launch, dropped libraries and the library the app reopens after an API library/switch. The HTTP API’s own library/switch still uses Library::open, so a damaged library fails there. Both refuse a library made by a newer Eagle than 4.0.0 (see Newer libraries and outside changes); the app shows an alert saying which Eagle version saved it.

Libraries chosen in the switcher or with Open Library… are read on a background thread (see Several libraries below). Libraries reopened on launch, dropped on the window, opened from Try Again or Select Another Path… and the one reopened after an API switch are read on the main thread.

The library switcher (the library name at the top of the sidebar, or ⌘L) lists the open libraries, then the recent ones that are not open. Each row shows the library’s icon.png at its left, or a folder glyph when there is none; the sidebar’s library row shows the same icon. Right-clicking a row, or the ⋯ button on it, opens a menu with Change Icon… (pick a jpg, jpeg, png, webp or gif; it is scaled to 64 px on its shorter side and saved as the library’s icon.png), Remove Icon (only when there is one; asks Remove or Cancel), and Show in Finder, and Remove from List, which takes the library out of the recent history (an open library stays open). Move to Trash… (a falcon addition; Eagle has no such command) moves the library folder to the macOS Trash. Falcon never deletes a library folder outright. It is shown for every library whose folder exists, and disabled with a hint while the library is open. A dialog names the library, shows its full path and size (counted on a background thread without following links or reading file contents, so iCloud placeholders are not downloaded; Move to Trash waits for it, and a failed count shows Size unknown), and says everything in the folder goes to the Trash and can be put back from Finder. Move to Trash is red; Enter does not confirm and Esc cancels. The rule (library_removal.rs) refuses unless the folder is a real directory, neither a link nor reached through one, named *.library with a metadata.json, and is not open, being opened, inside an open library or holding one (compared by path and by device and inode). It runs again right before the Trash call. If the Trash call fails an error toast shows and nothing is deleted or changed. Afterwards the library leaves the recent list and its remembered layout and icon, and a toast names it; backups elsewhere are untouched. Under the Recent section, Clear History… asks for confirmation in a Clear Library History dialog (Clear All or Cancel) and then keeps only the libraries that are open. Recent libraries are kept across launches even when their folder has gone: such a row is dimmed with a warning glyph and a tooltip saying the folder can’t be found, and its menu offers only Remove from List (Show in Finder is disabled). Clicking it tries to open it like any other library, which brings up the missing-library screen described under Several libraries.

Add to Other Library, in the item menu (one item or the selection), the menu of a folder (sidebar or folder card), of a smart folder and of a tag group heading, lists the recent libraries other than the shown one, then Choose Library… for any other. Several items ask first. The copy runs behind the progress modal with Cancel, and a notice says how many items were added and how many the other library already had. The rules are in Adding to another library. When the other library is also open in falcon, the items appear in its window at once.

Convert WebP, in the item menu when the item is a WebP, converts every still WebP in the selection to PNG or JPG (quality 100), after a warning that the files will grow, as Eagle’s does. It runs behind the progress modal with Cancel. The item keeps its name, tags and everything else and takes the new extension and size; its thumbnail stays, except that an image no larger than 960 px on both sides shows its original instead, as in Eagle. Animated WebPs are skipped. falcon writes the new file under a temporary name and swaps it in only when complete, moves the old WebP to the Trash instead of deleting it (the way to get it back, since the step can’t be undone with ⌘Z), and lays transparency on white for JPG (falcon_library::webp_convert).

Clear Invalid Content…, in the library switcher (Eagle hides it behind a modifier-click on its library button), scans the shown library’s item folders on a background thread. An item whose original file is missing is moved to the Trash (an item whose original exists is never treated as invalid); a folder in images/ that belongs to no item and has no metadata.json is moved to the macOS Trash (Eagle deletes it); an item whose folder has gone is dropped. Nothing found says how many folders were looked at. Otherwise falcon says what it found and warns that a cloud sync must have finished, then cleans up on Clean Up and reloads the library, as Eagle does. Folders with a damaged metadata.json are left alone (falcon_library::repair).

Falcon refuses to create, open or add to a library inside the folder it is installed in (its .app bundle, or the folder holding a bare executable), as Eagle refuses ones in its install folder: removing or updating the app would delete them.

Below the library rows the switcher lists Open Library…, New Library…, Merge Another Library…, Empty Cache and Reload…, Show in Finder, Import Files…, Import Folders…, Import Eagle Package… and Import Inboard Backup…, then the collect window and Preferences. The new entries are described under Several libraries.

Windows

Falcon builds and runs on 64-bit Windows, on Intel and AMD, from the same branch as the other systems. Only Windows 11 has been tried; ARM isn’t built. The installer, Falcon-x86_64-setup.exe, installs for the current user without admin rights in %LOCALAPPDATA%\Programs\Falcon, adds a Start menu entry and an uninstaller to Add or remove programs, and leaves libraries and settings alone when you uninstall. To upgrade, run a newer installer; Falcon doesn’t update itself. Falcon-x86_64-portable.zip holds the same app to unzip anywhere and run without installing: Falcon\falcon-app.exe at the top, with the FFmpeg DLLs in Falcon\lib, where Falcon looks for them after its own folder. It keeps its libraries and settings in the same places as the installed app; to remove it, delete the folder. It isn’t code-signed, so Windows SmartScreen warns on first run (More info, then Run anyway). File and message dialogs are owned by the main window (dialog_owner.rs), which Windows disables until they are answered; they block the frame that opens them, so an unowned dialog hidden behind the window would leave falcon looking frozen.

Video plays through the bundled FFmpeg (see Video playback).

Windows has the same gaps as Linux: screen capture, the tray icon, global hotkeys, the share sheet, system notifications, Touch ID, the login item, transparency effects, iCloud handling, QuickLook’s thumbnails, live web views and page screenshots, dragging items out of the window, opening files from the file manager and registering eagle:// links. Open With shows the system’s Open With window, and revealing several files shows only the first file in each folder.

Cloud AI providers can’t be used: falcon-ai keeps API keys only in the macOS Keychain and has no key store elsewhere, so a key can’t be saved. Local providers such as Ollama and LM Studio take no key and aren’t affected.

Where things are. Logs go to %LOCALAPPDATA%\Falcon\Logs, and settings and saved state to %APPDATA%\Falcon\data.

Item names on disk. An item’s name stays in metadata.json exactly as it came, but Windows can’t keep every name as a file. crates/falcon-library/src/disk_name.rs gives the name an item’s files are kept under: <, >, :, ", /, \, |, ?, * and control characters become _, trailing dots and spaces are dropped, and a device name such as CON or NUL gets a _ after it. An item named a:b is therefore kept as a_b.png, with the name in the metadata still a:b. Code builds an item’s file names through Item::original_path and Item::thumbnail_name, never from the name directly. The limit is that a library made or changed this way won’t find that file if it goes back to a Mac, which looks for a:b.png.

What it does

The Rename dialog for several items is Eagle’s: a name template (default Untitled - %N, then the last one used) with counters %N…%NNNN, dates %D, %M (file modified) and %B (created) in five forms, %T tags and %F folder names (each sorted and joined with -) and * the original name, counting from Start at; or a find and replace (plain text or /pattern/flags). A case change applies to either, a preview lists every new name, and ten or more items ask first. As in Eagle, templated names lose /, % and emoji, and an emptied name keeps the original; the library then makes the name safe for a file and renames the original and its thumbnail.

Empty views

An empty grid says why, with an icon, a title and a line of text (crates/falcon-app/src/ui/grid/empty.rs, where the wording and rules are tested). While a search or any filter is active it reads “No Matches”. Otherwise All, Recently Used and Random say “Drop Files Here” with an Import Folders… button, and so does a folder with no subfolders (a folder with subfolders shows only its subfolder cards, and a locked one its lock screen). A smart folder with no matches says so. Uncategorized and Untagged explain what gathers there, or say “All Sorted” and “All Tagged” when the library has items and none are left. The Trash says it is empty. The All Tags page says “No Tags Yet” when the library has no tags, and “No Matches” when its filter finds none.

Date, duration, BPM, camera and font filters

Five chips follow the existing ones in the filter bar. They set the imported, modified, created, duration, bpm, cameras and font rules of the library’s Filter (see Search and filters), so the grid applies them like any other rule. The code is in crates/falcon-app/src/ui/filter_bar/media.rs, with the parsing and labels in logic/ (BPM’s are in ui/filter_bar/media.rs).

What Eagle does, from js/directives/filter-item-import.html, filter-item-mtime.html, filter-item-duration.html, filter-item-bpm.html and .js, filter-item-camera.html and filter-item-fonts.html:

Viewer layout

Every viewer (image, GIF, RAW, SVG, video, audio, font, text, PDF, the cannot-preview page and the iCloud wait screen) opens in the middle of the window, in place of the toolbar, filter bar and grid, with the sidebar and the inspector still beside it, as Eagle’s detail mode does. The inspector shows the viewed item: the selection follows it as you step through, so closing the viewer leaves the grid on that item. The viewer draws only inside its own rect, and its scroll, pinch, clicks and menus act only there. The span is logic::viewer_span; the bar is media_view::bar_shell, shared by every viewer.

What Eagle does, from the detail mode in index.html and app.bundle.js:

Image viewer

Images, RAW photos, SVGs and the formats shown as a picture (PSD, Office files and the like) open in the image viewer, drawn in crates/falcon-app/src/ui/viewer/image.rs with its rules in logic/.

What Eagle does, from index.html, the BitmapViewer and zoomer in app.bundle.js and js/default-preferences.js:

Audio and font viewer

Opening an audio item (Eagle’s mp3, wav, flac, ogg, aac and m4a; see Audio formats) shows its waveform with playback controls instead of an image; opening a font shows a specimen drawn with the font itself. The code is in crates/falcon-app/src/audio.rs (playback and the waveform cache), crates/falcon-app/src/ui/viewer/audio.rs (the audio view), crates/falcon-app/src/ui/viewer/font.rs (the font viewer) and crates/falcon-app/src/font_install.rs (activation), with the seek and time arithmetic in logic/, the font information in fontmeta::FontInfo and the language change in Library::set_font_language.

What Eagle does, from js/directives/audio-media-element.js, its video.js setup in app.bundle.js, js/default-preferences.js and font-viewer/:

Audio formats

Eagle 4.0.0 treats six extensions as audio (mp3, wav, ogg, flac, aac, m4a: the audio viewer’s ng-switch-when in index.html, the hover selectors in js/hover-preview/audio-hover-preview.js and the thumbnail list in app.bundle.js) and plays them with Chromium. Every other sound file (opus, aiff, wma, ape, amr, caf…) is a plain file there, with no player, waveform or duration. Falcon does the same: only those six are audio items (media::AUDIO_EXTENSIONS), and other sound files import as plain items with a QuickLook thumbnail. Opus is decoded inside .ogg and .m4a files, which Chromium plays too.

Decoding is falcon_library::audio. audio::open returns an AudioSource: interleaved f32 blocks, the rate and channels, the length and an accurate seek. The first backend is symphonia 0.5.5 (pure Rust, MPL-2.0) with the pure-Rust opus-decoder crate for Opus; when it can’t read a file and an LGPL FFmpeg is installed, audio::open tries FFmpeg (audio/ffmpeg.rs, see Video playback), which also reads the soundtracks of video files. The app wraps the source as a rodio source; waveform::peaks, media::audio_duration and tempo::bpm read the same source.

Fixes falcon makes around symphonia 0.5.5, each in crates/falcon-library/src/audio/:

• adts.rs replaces symphonia’s ADTS reader, which only syncs on FF F1 and guesses the length from the bitrate: it indexes every frame at open, so the length is exact and seeks land on the frame.
• edit.rs reads the MP4 edit list and the iTunSMPB tag, which symphonia parses but doesn’t apply, so an Apple AAC file is 1.000 s long rather than 1.152 s and its audio starts at 0.
• opus.rs adds the Opus decoder symphonia 0.5 lacks, and the source trims the Ogg pre-skip and decodes 80 ms before a seek’s time so the decoder settles.
• An MP4 whose sample entry gives a different rate from the ALAC header plays at the codec’s rate.
• When a reader can’t seek from where it is, the source reopens the file and seeks again, and if a reader can’t seek at all it decodes from the top and drops up to the time.

Gaps:

• HE-AAC (SBR, PS) plays its AAC-LC core only, at the core’s bandwidth. AAC Main, LTP and more than two AAC channels don’t decode.
• Raw AAC carries no priming information, so an .aac file starts with the encoder’s silence (about 2112 frames) and reads that much longer than its source.
• Speed changes move the pitch (rodio resamples), as described under Speed.

Text viewer

Opening a text item (.txt) shows its text on a page in the viewer, editable in place, instead of a QuickLook picture. The drawing is crates/falcon-app/src/ui/viewer/text.rs, the rules (when to save, how a file is read) are crates/falcon-app/src/textdoc.rs, and the save itself is Library::save_text in crates/falcon-library/src/text.rs.

What Eagle does, from text-editor/text-editor.js, text-editor.html and its stylesheet:

Video viewer

Opening a video shows it with a control bar instead of the image viewer. AVFoundation plays what macOS can (mp4, mov, m4v and the other QuickTime and MPEG-4 files with H.264, HEVC, ProRes and similar codecs). Files it refuses (Matroska, WebM, AVI, WMV, FLV, MPEG-TS and others) play through FFmpeg when it is installed, in the same viewer; see Video playback and the FFmpeg fallback. Both go through the falcon-video crate (crates/falcon-video), which keeps every Objective-C call in one module and hands the app RGBA frames to upload as a texture. FFmpeg is LGPL and loaded at run time, never linked, so falcon stays MIT/Apache-2.0. The drawing, keys and timed comments are in crates/falcon-app/src/ui/viewer/video.rs.

What Eagle does, from the mediaElement and mpvMediaElement directives and the comment dialogs in app.bundle.js, its stylesheets and js/default-preferences.js:

GIF and animated images

GIFs, animated WebPs and animated PNGs (APNG) play in the image viewer, every frame, looping. A player in crates/falcon-app/src/anim.rs decodes them on a background thread and keeps only a window of frames around the playhead, so a GIF of thousands of frames opens at once and uses about as much memory as a short one: a GIF’s blocks are walked once to find each frame’s offset and delay without decompressing anything, and each frame is then read from the file, decompressed and composited when playback needs it, with snapshots of the canvas every few frames for seeking. WebP and APNG frame counts and delays come from their chunk headers, and the image crate decodes their frames in order. Still WebPs and PNGs take the image viewer’s usual path. The player bar is crates/falcon-app/src/ui/viewer/gif.rs.

What Eagle does, from the GIF branch of the viewer in index.html, the gifViewer code in app.bundle.js, gif-viewer/ and js/default-preferences.js:

PDF viewer

Opening a PDF shows it in a reader instead of the image viewer: the pages in one continuous vertical column, with zoom, page navigation, find, text selection and a thumbnail/outline sidebar. Pages are drawn by macOS’s PDFKit through the falcon-pdf crate (crates/falcon-pdf), which keeps every Objective-C call in one module and hands the app RGBA pictures. The reader is in crates/falcon-app/src/ui/viewer/pdf.rs.

The file is opened, rendered, searched and selected only on a worker thread, never on the UI thread, so a PDF whose contents are still in iCloud (or a 1,000-page book) can’t freeze the window. While it opens the viewer says “Opening…”, or “Downloading from iCloud…” when the file is dataless (its SF_DATALESS flag is set, read without starting a download; pdf_view::icloud_only is the one place to switch to a shared iCloud helper). A file PDFKit can’t read shows a line saying why; a password-protected one asks for its password (see below). Off macOS the image viewer shows the preview instead.

Rendering: the UI asks the worker for the pages in view and one on either side, at the screen’s pixel density rounded up to steps of about 4%, so pages are never blurry at rest. Each page picture is capped at 16 MP (pdf.js’s own canvas cap), so past roughly 400% on a Retina screen a page is shown enlarged rather than re-rendered sharper. Pictures live as textures in an LRU cache of 128 MP for pages and 16 MP for thumbnails. While the zoom is moving, pages keep their old picture scaled; 160 ms after it stops they are rendered again at the new scale.

What Eagle does, from app/pdf-viewer/ (pdf.js 3.1.81 with Eagle’s edits in web/viewer.html and web/viewer.js) and the detail view in app.bundle.js and index.html:

Web page viewer

What Eagle does, from the url|html|mhtml branch of the detail view in index.html and getURLSrc in app.bundle.js:

3D model viewer

Opening an obj, stl, ply, glb, 3mf, fbx, dae, 3ds or ifc item (Eagle’s model formats; a .gltf is a plain item with a QuickLook thumbnail, as in Eagle) shows the model in an interactive viewer in the central panel, like the other viewers, with the shared bar (panels, back, counter, open, previous and next; Esc and ← → work as usual). The readers and geometry are crates/falcon-library/src/model3d/ (one file per format, geom.rs for normals, edges, details and lighting, math.rs for vectors and matrices). The camera maths are crates/falcon-app/src/logic/viewer3d.rs, the viewer’s state and vertex data crates/falcon-app/src/model3d/, the wgpu drawing model3d/gpu.rs and the viewer itself ui/viewer/model.rs. An ifc file is read through web-ifc when falcon is built with it (see IFC below); without it, an ifc file with no tessellated geometry keeps its QuickLook still, as does any model that fails to read. Without the wgpu renderer every 3D item shows its still.

FBX

FBX files, binary and ASCII, are read by model3d/fbx.rs with the ufbx C library (MIT, https://github.com/ufbx/ufbx) through the ufbx crate, which compiles the vendored C source with cc.

• Every node with a mesh is drawn, with its world transform applied. Each material the node uses becomes one mesh in the tree, named after the node.
• Polygons are split into triangles with ufbx’s triangulation, which handles concave faces. Normals come from the file, or ufbx generates them when the file has none.
• Each material gives its diffuse colour (times the diffuse factor), its Opacity property, and its diffuse (or PBR base colour) texture: the picture embedded in the file’s Video content, else the file its relative or absolute name points to, looked up next to the model (see Textures below). UVs come from the first UV set, with the texture’s UV transform; wrap modes are not read, since every texture repeats, as in Eagle.
• The scene is converted to the viewer’s convention: right-handed, Y up. Sizes are in centimetres, the FBX default unit. The file’s UnitScaleFactor is applied, so a model saved in metres still reads in centimetres, and a Z-up file stands upright.
• Skinned meshes are shown in their bind pose. Blend shapes, animation, cameras, lights, NURBS, vertex colours and external files other than textures are skipped.
• A broken file is an error, never a crash. ufbx’s memory is capped (1 GiB while parsing, 2 GiB for the scene), node nesting is limited to 256 levels and output to 50 million vertices. The file is always parsed as FBX, so an OBJ renamed to .fbx is refused. An FBX without triangles is an error, like the other formats.
• The thumbnail at import, the Details panel, the mesh tree, measuring, snapshots and export work as for the other formats.
• The tests build a small box FBX in both encodings in code (ufbx can’t write files) and check the triangles, material, transform, generated normals, unit scale, Z-up conversion, empty scenes and truncated or corrupt files.

COLLADA and 3DS

model3d/dae.rs reads COLLADA 1.4.1 and 1.5 with roxmltree. It reads the meshes of library_geometries: triangles, polylist, polygons, tristrips and trifans, with polygons fan-triangulated and the holes of ph ignored. Sources go through their accessors (count, offset, stride, named params), giving positions, normals and vertex colours. The visual scene’s node tree is composed into world transforms from matrix, translate, rotate, scale and lookat, following instance_geometry, instance_node and instance_controller. A controller shows its skin’s or morph’s base mesh in the bind pose, after the skin’s bind shape matrix. The root asset’s up_axis and unit are turned into falcon’s Y-up metres the way three.js’s COLLADA loader does: Z-up turns -90° about X, X-up turns +X to up, and the unit scales. A mirroring transform flips the winding so faces stay outward. Each primitive’s material comes through the instance’s bind_material. Its colour is the effect’s diffuse colour (emission for constant). When the diffuse is a texture (through the 1.4.1 sampler and surface params, 1.5’s instance_image, or an image id used directly; a file next to the model or 1.5’s embedded hex data), that texture is drawn with the TEXCOORD set the instance binds through bind_vertex_input (else the first), (the sampler’s wrap_s and wrap_t are ignored); the material colour, used where the picture can’t be read, is the picture’s average colour, else the default grey. The reader skips animation, skinning weights, morph targets, cameras, lights, skew, lines and transparency. Without normals in the file the viewer shades flat, or smooth when Smooth shading is chosen.

model3d/threeds.rs reads binary 3DS chunks: the editor’s named triangle meshes (vertices, faces, per-material face groups, smoothing groups) and its materials (name, diffuse colour in the 0x0010 to 0x0013 forms, the gamma-corrected one preferred, transparency, and the diffuse texture map 0xA200 with its file name, scale, offset and rotation 0xA354 to 0xA35C, which are baked into the mapping coordinates 0x4140; the picture’s average colour replaces the diffuse colour for when it can’t be drawn). Each object gives one mesh per material, plus one without a material for ungrouped faces. With smoothing groups, every corner’s normal averages the faces meeting at that place that share a smoothing bit, and group 0 stays flat. Without smoothing groups the faces shade flat. The vertices are already in world space, so the local axis matrix (0x4160) is not applied, and coordinates are kept as stored (Z up, like 3MF and STL; the viewer’s up setting turns them). The reader skips the keyframer (0xB000), lights, cameras and the master scale. Every count is checked against the bytes left in its chunk before anything is allocated.

Both readers return an error for a truncated or corrupt file instead of panicking. Tests cut a file at every byte and damage bytes one at a time. They also cap node visits, nesting depth and triangle totals (COLLADA) and distinct smoothing masks per vertex (3DS).

Textures

glb, obj, fbx, dae and 3ds draw their diffuse (base colour) texture in the viewer, in snapshots and in import thumbnails, as Eagle’s viewer does. 3mf, ply and stl have no textures, in falcon or in Eagle’s viewer. Each mesh carries its texture coordinates (in picture space, v down) and a texture (model3d::texture): the decoded picture, a tint and an optional alpha cutoff. Textures always repeat.

• Where pictures come from: the GLB’s binary chunk, a data URI or an image file a GLB names, an MTL map_Kd, FBX embedded media or its file name, COLLADA library_images, and the 3DS texture map’s file name. Files are looked up only next to the model or in a folder below it: a relative path that stays inside is tried as written (an MTL’s maps first next to the MTL), and every name, including an absolute path or one climbing out with .., is also tried as its bare file name next to the model. Nothing outside the model’s folder is read. A missing or unreadable picture leaves the material colour, as before.
• Memory: a picture is decoded to at most 4096 pixels on its longer side (scaled down by ImageIO while decoding on macOS, so a 10000 × 10000 picture never sits in memory at full size) and one model’s pictures together take at most 64 MB of RGBA; a picture that doesn’t fit what is left is halved until it does, or skipped. The same file or embedded bytes are decoded once. The viewer lets go of the model, its pictures and their GPU textures as soon as a frame goes by without drawing it (another item, a closed viewer).
• Colour: glTF multiplies the picture by its base colour factor; the other formats draw the picture in place of the material colour (Online3DViewer’s multiplyDiffuseMap is set only for glTF). Vertex colours multiply in as well. The multiply is done in linear light and the result lit like an untextured face.
• Placement: glTF KHR_texture_transform, MTL -o and -s, FBX UV transforms, and 3DS scale, offset and rotation. Eagle’s viewer always repeats textures, whatever wrap mode the file names (glTF samplers, MTL -clamp, FBX wrap modes, COLLADA wrap_s/wrap_t, 3DS tiling flags); falcon reads none of them and repeats too, in the viewer, snapshots and thumbnails. glTF’s MASK alpha mode cuts out pixels under its cutoff; Above the cutoff, MASK pixels blend with their alpha, as they do in Eagle’s viewer.
• The GPU uploads each picture as an sRGB texture with mipmaps made on the CPU in linear light and samples it trilinearly with 16× anisotropic filtering. The thumbnail rasterizer samples it bilinearly in linear light at perspective-correct coordinates.
• Not drawn: specular and metal-roughness maps. Exports keep geometry and material colours only; textures are not written.

Normal, bump and emissive maps and transparency

Falcon draws what Eagle’s viewer draws for each format, which is less than some formats can carry. Online 3D Viewer’s own readers handle glb, obj and 3ds. fbx and dae go through three.js’s loaders, and only colour, opacity, alpha test, diffuse, normal and bump maps survive the conversion back.

3mf colour alpha stays opaque, as in Eagle’s viewer: its loader sets the opacity without marking the material transparent. A glTF material with KHR_materials_pbrSpecularGlossiness has no normal or emissive map and isn’t see-through, also as in Eagle.

• Coordinates: a mesh has one set, which every map reads. Its transform comes from the first of the base colour, normal, bump and emissive maps that the material has, as three.js picks one uvTransform.
• Normals: no tangents are stored. The frame comes from screen derivatives of position and coordinates in the shader, and from the triangle’s edges in the thumbnail rasterizer (geom::normal_mapped). Green points up the picture. A normal map wins over a bump map.
• Bumps: the height is in the red channel, in the model’s units, so the same map looks stronger on a small model, as in Eagle (geom::bumped). MTL’s -bm is ignored, also as in Eagle.
• Colour: normal, bump and emissive maps are uploaded as stored, with plain mipmaps, and emissive light is added to the lit colour in display values, because Eagle’s viewer applies no colour conversion to them.
• Blending: see-through meshes draw after everything else, including lines, farthest first by the middle of their bounds; each draws its back faces and then its front faces, writing depth as it goes. Alpha is the opacity times the picture’s alpha. This is three.js’s order, so it shares its faults: parts that interleave can hide each other.
• Memory: maps count towards the same 64 MB per model, and each may take only half of what is left, so they can’t starve the pictures of materials read later. Missing or bad maps leave the surface as if the file had none. Thumbnails and snapshots draw all of this in the same order.

IFC

IFC geometry comes from web-ifc 0.0.78 (MPL-2.0, https://github.com/ThatOpen/engine_web-ifc), the engine Eagle’s Online 3D Viewer uses (Eagle 4.0.0 ships web-ifc 0.0.34 as WebAssembly; falcon builds a newer release natively). scripts/fetch-web-ifc.sh downloads web-ifc and the header-only libraries it builds against (glm, tinynurbs, fast_float, earcut.hpp, CDT, spdlog, stduuid, unordered_dense; all MIT, BSD, ISC, Apache or MPL) as GitHub tarballs at pinned tags or commits, checks each against a pinned SHA-256 and unpacks them into target/web-ifc (or $WEB_IFC_DIR); nothing is committed and no CMake is needed. crates/falcon-ifc/build.rs then compiles web-ifc’s sources, unmodified, as C++20 with the cc crate (twelve seconds from a clean target/ on an 18-core machine; cc compiles them again only when the sources or worker.cpp change), and links them with falcon’s own crates/falcon-ifc/cpp/worker.cpp into one executable of 1.2 MB, falcon-ifc-worker, in the build’s output directory. On macOS the worker is built for 13.3 or later, since web-ifc formats numbers with std::format, which macOS’s C++ library has only from 13.3; on older systems it can’t start, and IFC files fall back to falcon’s own reader. Nothing of web-ifc is linked into falcon’s binaries. $FALCON_WEB_IFC_DIR points the build at another copy of the sources. Without them no worker is built, falcon_ifc::available() is false, and falcon reads only the tessellated part of IFC with its own reader, as described at the end of this section. scripts/bundle.sh copies the worker into Falcon.app/Contents/MacOS (falcon looks beside its own executable first, then where the build put it) and the licence of each component into Contents/Resources/web-ifc.

The file is read as Online 3D Viewer reads it (OpenModel with COORDINATE_TO_ORIGIN, then LoadAllGeometry): every product web-ifc knows except IfcOpeningElement, IfcOpeningStandardCase and IfcSpace, each placed geometry with its colour (styled item, material or web-ifc’s white default) and its placement matrix, lengths in metres, Y up, and the model moved so that its first vertex sits at the origin. web-ifc meshes extruded, tapered, revolved and swept-disk solids with every parametric profile (rectangle, rounded and hollow rectangle, circle and hollow circle, ellipse, trapezium, I, L, U, T, C and Z shapes, arbitrary closed profiles with polyline, composite, trimmed and indexed curves, profiles with voids), fixed-reference and surface-curve sweeps, IFC 4.3 sectioned solids, boolean results and clipping results (half-spaces and polygonal bounded half-spaces), openings cut from their hosts through IfcRelVoidsElement, CSG primitives (IfcBlock, IfcRectangularPyramid, IfcRightCircularCylinder, IfcRightCircularCone, IfcSphere), advanced breps with planar, cylindrical, revolved, linearly extruded and b-spline faces (rational or not), mapped items and every tessellated form. Curves (axes, curve sets) are not drawn, as in Eagle. Circles use web-ifc’s default of 12 segments per turn. Not meshed by this web-ifc release: IfcSectionedSpine, IfcBoxedHalfSpace, IfcRevolvedAreaSolidTapered, IfcMirroredProfileDef, and advanced brep faces on toroidal, spherical or conical surfaces; a product built only from those counts as skipped with the type named under Not Read.

web-ifc runs in a process of its own for each read, because a malformed file can make C++ overflow its stack, spin forever or read out of bounds, and no thread survives those. falcon writes the limits and the file to the worker’s stdin and reads the geometry from its stdout as it comes (crates/falcon-ifc/src/worker.rs; the protocol is at the top of worker.cpp). The worker reads on a thread with a 256 MB stack, catches C++ exceptions (a product web-ifc can’t process is left out while the rest are read), and exits at once on a fatal signal, so a crash leaves no crash report. It ends itself past 120 seconds or 16 GB of memory, which also covers a falcon that has gone, and falcon kills it two seconds after that. A crash, a hang or a runaway allocation therefore reaches falcon only as an error from falcon_ifc::read, and the next file reads normally. One file is read at a time, and reading stops past 20 million triangles (“IFC: the model is too large”). Files over 256 MB are not read. A file with references that dangle, form a cycle or chain deeper than 10,000 gets 30 seconds instead of 120: web-ifc reads most such files fine but can spin on some. Starting the worker costs a few milliseconds per file. The file is also parsed by falcon’s own STEP parser first (below); a file that parser refuses is not handed to web-ifc. A file web-ifc can’t read, whatever the reason, falls back to falcon’s own reader, and the inspector’s 3D Preview row then says so (“IFC: web-ifc could not read this file”) above what that reader found. Meshes are grouped by product type and colour, so the tree lists IfcWall, IfcSlab, IfcWindow and can hide each kind. The bridge is crates/falcon-library/src/model3d/ifc_native.rs.

For the inspector, a product counts as shown when web-ifc drew at least one triangle for it. One that came out empty counts as skipped only when it has a drawable shape representation (Body, Facetation or any other except Axis, FootPrint, Box, Annotation and similar), and Not Read lists that shape’s geometry types (through mapped items). Products cut away whole by their openings (frame placeholders filled by their opening, for instance), products without a shape, and openings, spaces, zones, virtual elements, annotations and grids are neither.

Across 117 sample files (none committed), no file falls back and every product Eagle’s own engine draws is drawn. The set is the IFC 2x3, IFC 4 and IFC 4.3 certification scenes and the IFC4.x specification models from buildingSMART (81 files), eight IFC 2x3 Coordination View 2.0 files of the Schependomlaan project and the 28 files in web-ifc’s own tests/ifcfiles/public. They were also run through Eagle’s web-ifc.wasm (0.0.34) under Node: it drew 56,458 products and falcon drew all of them and 1,257 more (IFC 4.3 alignments and advanced breps, among others), and the one file that aborts Eagle’s engine reads here. In 60 files the two agree exactly; elsewhere triangle counts differ because the two releases mesh and cut differently. Empty products are curves (IfcGeometricCurveSet, IfcGeometricSet), which neither draws, and the five files that draw nothing hold only curves or geometry on type objects. The largest file, 69 MB, takes 2.6 s and 307 MB in the worker, for 1.6 million triangles; the 47 MB Schependomlaan model takes 0.9 s. FALCON_IFC_SAMPLES=<dir> cargo test --release -p falcon-library --test ifc_samples -- --nocapture prints a line per file, and FALCON_IFC_FUZZ_DIR=<dir> cargo test -p falcon-ifc --test isolation damaged_sample_files reads damaged copies of each file (71 files, 20 rounds each, survived).

Without web-ifc, IFC is read only as far as its tessellated geometry goes (model3d/ifc.rs, with the STEP parser in model3d/step.rs and ear clipping in model3d/earclip.rs). The STEP parser reads the header’s schema and the DATA; section’s #id = ENTITY(args); instances with nested lists, strings (with their \X2\ and similar escapes), enums, $, *, references and typed values, wherever the line breaks and comments fall; it works on tokens with an explicit stack and refuses lists nested more than 64 deep. Drawn: IfcTriangulatedFaceSet (an IfcCartesianPointList3D with its coordinate index, point index and normals), IfcPolygonalFaceSet (indexed faces, with voids), faceted breps (IfcFacetedBrep and IfcFacetedBrepWithVoids, their closed or open shells, IfcFace with IfcFaceOuterBound / IfcFaceBound poly loops, holes included) and shell- or face-based surface models built from the same faces. Faces that are not triangles are cut by ear clipping on the plane they face most, holes joined to the outline by a bridge. Each product (anything with an IfcProductDefinitionShape, except openings, spaces, zones, virtual elements, annotations and grids) is placed through its Body shape representation (other drawable representations when Body has none), IfcMappedItem (up to 8 levels deep) and its IfcLocalPlacement chain. Lengths are converted to metres from the project’s IfcUnitAssignment, IFC’s Z up becomes the viewer’s Y up, and a model more than 10 km from the origin is moved to it. Colours come from an IfcStyledItem on the geometry, else from the product’s or its type’s material, else from a default per entity type. Swept solids, CSG and boolean results, b-spline surfaces and advanced breps are not read by it: a product with only such geometry counts as skipped, and a file with no tessellated geometry at all fails to read (“IFC: no tessellated geometry”), so it keeps its QuickLook still.

The item inspector lists, under Properties, for an ifc item: Products Shown, Products Skipped, Not Read (the unread geometry types with their counts, the three most common), Triangles and Schema, or 3D Preview with the reason when nothing can be drawn (“IFC: no 3D geometry” with web-ifc, “IFC: no tessellated geometry” without) (model3d/ifc_facts.rs, read on one background thread at a time and kept per item; ui/inspector/ifc.rs).

What Eagle does: it embeds the Online 3D Viewer in an iframe (index.html near line 1443, model-viewer/) and forwards Esc, ← and → to the main window. The rows below come from that viewer’s behaviour.

The model is read on a background thread; the viewer shows “Loading model…” meanwhile. Drawing goes through an egui_wgpu paint callback: the scene is drawn into the callback’s own 4× multisampled colour and depth textures (lines on top of slightly pushed-back faces), resolved, and copied into egui’s pass with premultiplied alpha. Textured meshes draw with a second pipeline (see Textures above). Material opacity is ignored. GPU tests (draws_a_cube_when_a_gpu_is_present, draws_a_textured_cube_when_a_gpu_is_present) render a cube, plain and textured, through the whole path when an adapter is available.

Duplicates

The sidebar’s Duplicates entry (after All Tags) opens a page that works like Eagle’s duplicate panel. Pick a method, Identical Files (byte-identical originals) or Similar Pictures (perceptual hash), and what to scan: All Items, the view the page was opened from (its items in grid order), or the items that were selected there (two or more). Scan runs on a background thread with a progress bar. Changing the method or the range clears the results.

Each group is a row of thumbnails under a checkbox (“N identical files” or “N similar pictures, the best copy picked”), and every group starts ticked. Each thumbnail shows its name, type, size, dimensions and, for similar pictures, its distance in bits from the first. The copy a merge keeps is outlined and marked “Kept”. For similar pictures falcon puts the best copy first and keeps it, as Eagle does: the most pixels, then for the same format the bigger file, else the better format (PNG, BMP, JPG, JPEG, WebP, AVIF, JXL, HEIC, HEIF, JFIF; merge::best_first). Clicking a similar picture keeps it instead, and for any group the thumbnail menu has Keep This Copy, Open, Open in Default App and Remove from Group. Remove from List drops a whole group. A group left with one item leaves the list. Double-clicking opens the viewer. The similarity slider sets how many of the 64 bits may differ (10 by default, right is stricter) and scans again. A line gives the number of picked files and the space a merge saves.

Merge Groups… opens a review of the ticked groups. For the chosen group it shows the kept item, then radio buttons for its File Name, Link and Note, picked from the group’s distinct values (the first by default), with Join all notes when there are several notes (joined by line breaks and cut to 4,096 characters, as in Eagle), and toggles for the group’s folders and tags, all on by default. Merge asks once more, then applies Library::merge_duplicates (crates/falcon-library/src/merge.rs). The kept item takes the chosen values and the group’s highest rating, and the others move to the Trash with their files untouched. A copy kept by one group is never trashed by another. The whole merge is one ⌘Z step: undo puts back the kept item’s name (its file renamed back), link, note, folders, tags and rating, and brings the others out of the Trash. A summary then gives the files moved to the Trash and the space saved, with Keep Merging (the merged groups have left the list) and Done (back to the start). The code is in crates/falcon-app/src/ui/grid/duplicates.rs, with the group rules in logic/.

The scan fills the hash cache item by item so it can report progress (content hashes only for files that share their size with another), then calls the library’s find_exact_duplicates_in or find_near_duplicates_in (see Import) on a copy of the library taken when the scan starts. Items outside the range never link two similar groups together. The cache is kept in memory for the session, keyed by item id and checked against the original’s size and mtime, so a second scan only hashes new or changed files. Nothing is written to the library until a merge.

What Eagle does, from js/directives/duplicate-scan-panel.html and .js, merge-editor.js and the import menu in app.bundle.js:

Duplicate check on import

Every import from the app (drops, ⌘V, files passed to the app, the collect window) checks whether each file is already in the library, while the preference is on. The import thread stages the file without the library lock, takes the lock only to list items of the same size and extension, and compares the bytes with the lock released (import_check, see Import). A match is not committed: the staged copy is held in a queue and the thread goes on with the next file. When the batch has finished, the window takes the queue into a dialog; the thread never waits for the window. The code is in crates/falcon-app/src/import_dupes.rs (thread side and decisions, with tests) and ui/dialogs/duplicates.rs (the dialog).

The dialog, “Already in the library (N)”, shows the existing item’s thumbnail, name and first folder, the new file’s size and target folder, two choices, Use the existing item (the default) and Keep both, a “Do the same for all N files” box when more than one file is held, and Import and Don’t Import buttons. Return imports with the chosen option and Esc skips; with ⌘ held either answers for every file. A click outside doesn’t answer. Use the existing item puts the existing item in the import’s folders with their auto-tags and moves its date added to now (Library::use_existing_for_import); if that item has been deleted or trashed meanwhile, the file is imported instead. Keep both commits the held copy as a new item. Don’t Import drops it, removing the staged copy. Each answer is one undo step and shows a notice (“Used the existing items for 2 files”). Held files count as done in the progress bar’s “Added N”. Held files still waiting when their library is closed are dropped.

AI Search

AI Search finds pictures by describing them (“black cat”) or by showing a similar one, on the Mac. Eagle does this with a plugin and an outside service; falcon has it built in, and it stays off until the model is installed. Descriptions should be in English: the model was trained on English captions, and other languages work poorly or not at all.

The code is crates/falcon-clip (the model, its download, the index and the worker, so the rest of the workspace doesn’t rebuild the ML dependencies), crates/falcon-app/src/ai_search.rs (the engine handle, one library’s search, the Preferences pane) and crates/falcon-app/src/app/ai_search.rs (the impl App part).

The worker owns the model and drops it after two minutes with nothing to do, since it holds about 600 MB. Searches go ahead of indexing, and run off the UI thread; the answer is picked up in ai_tick. The index is searched by comparing with every vector, so a library of 100,000 items holds about 200 MB of vectors in memory.

Tests use a stand-in embedder (crates/falcon-clip/tests/service.rs), so cargo test needs neither the network nor the weights. crates/falcon-clip/tests/real_model.rs holds the tests against the real model, #[ignore]d, and says how to run them.

Menu bar

On macOS falcon has a native menu bar, built with AppKit in crates/falcon-app/src/menu.rs. It follows the order of Eagle’s menus (app.bundle.js, seen) and holds only what falcon can do:

• Each item shows its chord from the shortcut table (Undo, Redo and Cut show egui’s fixed ⌘Z, ⇧⌘Z and ⌘X). The menus are rebuilt when the bindings, the language or the library’s actions change, so a chord changed under Preferences → Shortcuts shows at once, an unbound command shows none, and the menu titles and items follow Preferences ▸ General ▸ Language (see Localisation).
• An item is enabled when its command can act, by the same rules the keys follow (menu::enabled): Rename needs a selection and no viewer, Add to Last Used Folder a folder used before, Custom Thumbnail one item (Reset only when it has a custom thumbnail; it resets the first item acted on, as Eagle does), Remove from Folder a selection inside a folder, the Move Folder ▸ entries an open folder or smart folder and not several picked ones (as in Eagle), Move Folder… picked folders or an open folder (it moves the picked ones if any, as Eagle’s does), Parent Folder a folder with a parent, Shuffle Again (R) the Random page or a folder or smart folder sorted at random (as Eagle’s refreshRandom), Next and Previous Library a second open library, the Edit Image entries an image of a kind falcon can flip, rotate or crop (Combine Images two or more images it can decode, outside the Trash and the viewer). Lock Falcon needs an app password. Color Space (sRGB, Display P3 or Unmanaged, Eagle’s colorSpace setting and its default) carries a checkmark on the choice. Everything is disabled while Preferences is open or falcon is locked. The open page, the layout, the caption switches, the sidebar, the inspector, the filter bar, the viewer, presentation mode, Always on Top, Grayscale, Navigator and full screen carry checkmarks. The app hands the menu a fresh state only when it changes; AppKit reads it when a menu opens.

Color Space. The App menu’s Color Space submenu, after Preferences as in Eagle (app.bundle.js, seen), offers sRGB, Display P3 and Unmanaged. Unmanaged is the default, as in Eagle, and the choice is kept in the preferences (color_space). colorspace.rs applies it by setting the colorspace of the window’s CAMetalLayer (the layer of wgpu’s Metal surface, a sublayer of the window’s content view’s own layer) to kCGColorSpaceSRGB, kCGColorSpaceDisplayP3, or nil for Unmanaged, at start and on every change. wgpu sets the layer’s colour space to nil each time it configures the surface, which it does on a resize, so falcon compares the layer with the choice every frame and sets it again when they differ. The submenu is disabled while Preferences is open or falcon is locked, as in Eagle.

This is separate from a picture’s own colour profile. falcon_library::color turns a picture with a profile into sRGB when the viewer shows it and when falcon draws its thumbnail, so an Adobe RGB or Display P3 file no longer looks dull. Colours outside sRGB are clipped. Rotating, flipping, cropping and exporting read the file’s own pixels through thumbnail::decode, which leaves them alone. Thumbnails made earlier keep their colours until refreshed.

• Keys stay with egui. Every falcon menu has a delegate that tells AppKit it has no key equivalents, so a key press never fires an item: egui gets it as before, text fields keep ⌘C, ⌘V, ⌘A, ⌘Z, ⌘← and the rest, and bare keys such as R or the digits still type. Should AppKit fire an item from a key anyway (the application menu has no such delegate, so ⌘, comes this way), falcon turns it back into the key egui would have had. Clicking an item runs the same App::run_command as its key. Undo, Redo, Cut, Copy, Paste and Select All act on a focused text field when there is one.
• Behind a dialog nothing else runs. While any modal is up (App::any_modal_open: the confirmations and prompts, the import prompts, the folder, tag, export and tool dialogs, Add to Folders, the tag picker, the Actions panel and its editor, Preferences and About) App::keyboard and the viewers’ key handlers return early and menu::enabled turns every item off, as Eagle’s modals do. What stays is the dialog’s own Return, Esc and typing, the window items (Minimize, Zoom, Full Screen, Always on Top), and Cut, Copy, Paste, Select All, Undo and Redo while a text field has focus. ⌘Q is the application menu’s own and always works.
• File ▸ New… (⌘N, file.create.new) and the + button in the sidebar header (tooltip “Add”) open Eagle’s New menu: a searchable menu (type to filter, as the context menus) under the button, or under the toolbar’s left end while the sidebar is hidden. It holds New Folder, New Subfolder (in a folder), New Smart Folder…, Import Folders…, Import Links…, Import Files…, Import Eagle Package…, an Auto-Import submenu (Settings… opens Preferences on the Auto-Import pane; while auto-import is on and a folder is set, a disabled row shows the watched folder), a Find Duplicates submenu (All Items; Current List, disabled when the view has no items; Selected, disabled unless more than one item is selected; each opens the Duplicates page set to that range), Sketch, Photoshop and Illustrator documents, Text Document, Word, PowerPoint, Excel and XMind documents (blank files falcon generates), and an Other Documents submenu listing the blank documents it can’t write (XD, Keynote, Pages, Numbers, MindNode) disabled. Import Links… sits after Import Folders… (see Importing links). The Pinterest and ArtStation entries are left out (ui/menus/new.rs).
• Left out because falcon can’t do them yet: the link and site importers and folder exports from the menu, Duplicate, custom thumbnails from the menu, Open Link, the caption toggles, Lock and Color Space, and the online Help items.

About

Falcon ▸ About Falcon opens a small window centred over the app: the app icon, the name, “Desktop asset manager for Eagle libraries”, the version (from the crate version) and a line saying the code is licensed under MIT or Apache-2.0. OK, Esc or a click outside closes it. While it is open the menu commands wait, as they do behind Preferences. On the first menu build falcon removes winit’s stock About item and inserts its own at the top of the application menu (menu::ABOUT); it is always enabled.

Tips

Help ▸ Show Tips opens a card over the window, on a dimmed background, with six short tips, one at a time: adding files, the viewer, search, filters, tags and smart folders, and jumping to a folder. It is a falcon addition; Eagle has no such overlay (its tutorial is a video link on its website). The card shows the tip, “1 of 6”, Back and Next (Done on the last tip) and a close button. Esc, the close button and Done all close it. Nothing has to be read to carry on. A click outside does not close it. While it is open the menu commands and keys wait, as behind About.

A tip that names a key shows the key as it is bound now (Preferences ▸ Shortcuts), and leaves the key out of the sentence when the command has none. Show Tips has no default key and works with no library open, and always starts at the first tip.

The tips also open by themselves, once: after the welcome flow is finished, a library is open and no dialog is up. Closing them by any route is remembered (tips_seen in the saved state), so they don’t come back. State saved by an earlier version has no tips_seen, so a user who has already used falcon sees the tips once on the first launch after the update. The rules are in tips.rs (should_show_on_launch), the card in ui/dialogs/tips.rs. Nothing is fetched or sent.

Error logs

Falcon writes errors, such as a library that fails to open or a crash, to ~/Library/Logs/Falcon/falcon.log (%LOCALAPPDATA%\Falcon\Logs on Windows), one line each with the local time and ERROR. When the file passes 1 MiB it is renamed falcon.1.log (replacing an older one) and a new log starts. Help ▸ Error Logs opens the file with the default app, creating it first if it is missing. The log is for diagnosis only; nothing is sent anywhere.

Debug report

Help ▸ Export Debug Report… asks where to save (the Desktop and Falcon Debug Report.zip by default) and writes a zip. It holds debug-report.txt, the open library’s metadata.json, mtime.json, tags.json and saved-filters.json when they exist, and the error log as falcon.log. The text has sections for the app (version), the system (macOS version and build, model, CPU, logical CPUs and memory, asked of sw_vers and sysctl, with “unknown” for anything that fails), the display (window size in points and pixels per point) and the library (path, item, folder and tag counts, each JSON file’s size and whether it is writable, then the other open libraries and the recent ones). Without an open library that section says so. The zip is made with ditto from a temporary folder that is deleted afterwards, then shown in Finder. Nothing is tested over the network or on the disk, and nothing is sent anywhere; the report may contain library paths and tag names, so look through it before sharing. A failure is logged and shown as a message.

Dropping files from Finder

While files are dragged over the window from Finder or another app, falcon shows where they would land, as Eagle’s drop areas do (index.html box-container-droparea and sidebar-droparea, seen): over the grid a framed hint says the files will be imported (into the open folder, when one is open); over the sidebar, that folders dropped there are imported with their subfolders; over a folder row, the row is outlined. The target is worked out the same way as for the drop itself (drop_pos::target), from the system’s mouse position, since macOS sends no mouse moves during the drag (crates/falcon-app/src/ui/drop_hint.rs).

Context menu search

As in Eagle (app.bundle.js, showSearch: true, seen), the item, folder, smart folder, tag, tag group, palette swatch, filter bar + and Saved menus, and the New… menu, open with a search box on top that already has focus, so you can type straight away. Typing replaces the menu with the entries whose label holds every typed word (any case), earliest match first; ↑ and ↓ move the highlight, Enter or a click runs the entry, Esc closes the menu. Disabled entries and submenu buttons are left out, as in Eagle. Entries inside submenus are searched too and listed under the submenu’s name, after the top-level matches (before them when no top-level label starts with what was typed and a submenu entry’s own label matches, as Eagle orders them); typing a submenu’s name lists its entries. Clicking into the box doesn’t close the menu. In the Saved menu the per-filter ⋯ submenus (Rename, Move, Remove) are left out of the results, so the search finds saved filters by name. The nested menus are searched as well: Change Icon in the folder and smart folder menus (while filtering, the icon grid becomes one entry per icon, labelled with its glyph and Eagle’s icon name, so “film” finds the film icons), Add to Group and Move to Group in the tag menu, and the batch rename dialogs’ Insert button, whose menu has its own search box and finds the Number and Date entries (a date form is listed under its source, Date ▸ Today, Modified or Created, so “modified seconds” finds one entry; ui/menus/insert.rs). Eagle’s inspector Help button is not built: its menu is mostly online links (Help Center, Tips, Roadmap, Privacy, API documentation, Twitter, Check for Updates) beside About, Preferences and Shortcuts, which falcon has in the app menu.

The Help menu in the menu bar is registered with macOS as the application’s help menu (NSApplication.setHelpMenu, as Eagle’s role: 'help' does), so macOS adds its own search field at the top of it and finds every menu item of the app by title. That field is the system’s, not falcon’s. Eagle also has a Help button at the foot of its inspector whose menu is searchable (About, Check for Update, Preferences, Help Center, Tips, Shortcuts, Privacy, API, Twitter); falcon has no such button.

crates/falcon-app/src/ui/menus/search.rs wraps a menu’s body without changing it: while you type, the body still runs each frame out of sight, the app collects its enabled buttons and their labels, and running an entry hands that button an accessibility click, so the menu code acts exactly as if it had been clicked. egui only builds a submenu while it is open, so the menus open theirs with menu_search::submenu(ui, name, |ui| …) instead of ui.menu_button: while the search filters, it runs the submenu’s contents inline in the hidden body and reports the area they took, so their buttons are collected under the submenu’s name; otherwise it is ui.menu_button. The item menu (Open File Location, Open With, Copy, Thumbnail Background, Export) and the folder and smart folder menus (Password, Sort Items By, Export) use it; Change Icon’s icon grid is left out of the search.

Keys

These are the defaults. All but the arrows, Esc, Tab, Z and the viewer’s C, 0, 1, +, − and ` can be changed under Preferences → Shortcuts (see Shortcut settings); the video and audio player keys are its Player group. Bare keys (the digits, R, T and /) don’t answer their ⌥ chord. Apart from the Player keys, every rebindable command is also in the menu bar (see Menu bar).

Saving

The app opens libraries in batched write mode (see Write batching): edits made during a frame, including those from the HTTP API and background imports since the last frame, are written together at the end of the frame. Pending writes are also flushed when a library is closed and, for every open library, when the app saves its state (every 30 seconds and on quit). A failed write shows “Could not save”. A metadata.json write is refused when the file on disk was saved by a newer Eagle or has a later modificationTime than falcon last saw, which means another app or a sync service changed it (see the write guard). The app then shows a Library changed elsewhere alert saying falcon didn’t save over it, reloads the library from disk and asks the user to redo the last change if it is missing. Other pending writes go out first. If the library can no longer be opened, because it is now from a newer Eagle or its folder is gone, it closes with a Library closed alert.

Metadata backups follow Eagle’s timing (see Backups). When a flush writes mtime.json or metadata.json, a backup is scheduled 1 second later, and each further write restarts the wait. Every open library is also backed up every 30 minutes. Both run backup::backup_library on a background thread, so the copy never blocks the window, and a library never has two running at once. The copy goes into the library’s backup/ folder, is skipped when the newest backup has the same size, and at most 100 are kept. Each new backup also replaces the library’s copy in eagle-backup/ in falcon’s app data folder (~/Library/Application Support/Falcon/eagle-backup/<fnv1a-32 of the library path>.json), and a backup never recreates a library whose folder has gone. When a library closes or the app saves its state with a backup still waiting, it is taken right away on the main thread so a quit doesn’t lose it. The timing lives in crates/falcon-app/src/backups.rs, whose Schedule takes the time as an argument and has unit tests; nothing in the tests waits on a timer.

Metadata backups have no setting: falcon backs up after a change the way Eagle does (Eagle has no preference for it either). An earlier “Back up metadata on change” checkbox that did nothing was removed; old saved state that has it still loads.

Status messages

Short notes appear in a small rounded box at the bottom centre of the window (in the middle of the picture while the viewer is open). Only one shows at a time, and a new note replaces the old one. A note stays up while the pointer is over it.

• Quick confirmations, such as anything copied, a rating or “Refreshed”, go after about a second.
• Other notes stay for three seconds, or longer when the text is long (one second less over the viewer).
• A failure (“Could not save”, “Export failed” and the like) has a red mark before the text and stays for at least six seconds.
• Notes for actions that can be undone have an Undo button at the right and stay for at least five seconds. Clicking it undoes the last step, as ⌘Z does, and closes the note. It is offered after moving items to the Trash, removing items from a folder, adding or dropping items on a folder, clearing or pasting tags, and renaming, removing or merging tags. Restoring from the Trash and permanent deletes have no Undo button.
• Notes about adding or moving items to a folder end with the folder’s name as a link. Clicking it opens that folder.

The import error box and the progress bars are separate and unchanged.

Notification Center

A falcon addition; Eagle has no such panel. Window ▸ Notification Center (no default key; the shortcut window.notifications can be bound in Preferences) shows or hides a window listing the notes above, the Collect window’s status lines and the dialog notices (a library that is too new, a merge that finished, and the like), newest first. It does not block the app and opens with or without a library. Esc closes it unless a dialog, menu or text field has the key. Each row has its time (the clock time for today, else the date and time), a red mark for a failure, a count such as ×3 when the same text was shown several times in a row (they are one row), and the text, wrapped and selectable. The Clear button empties the list. Only the text is kept: the Undo button and folder link of a note are not replayed. A dialog notice is listed as its title and body. The most recent 200 are kept, across restarts and for every library together (they are saved with the rest of the app state). The Collect window’s own status line is not listed. The list is notice_history.rs; every flash* call goes through set_toast, which records the text once, however long the note stays up.

Background task status

Eagle shows a small spinner beside the library name while its background queue (colour analysis of new items) has work; its tooltip reads Processing or Paused with the number left, and a click pauses or resumes the queue. falcon analyses colours as part of each import, so its queue is the import thread: while files are left, a turning ring sits beside the library name (ui/sidebar/task_status.rs, rules in tasks.rs) with the same tooltip. Clicking it pauses the queue before its next file (the file being imported finishes), shows a resume glyph and turns the strip under the toolbar to “Paused at N of M”; clicking again resumes. Thumbnail refreshes run behind their own progress window with Cancel and are not part of this queue.

Several libraries

Falcon can keep several libraries open in one window and switch between them; Eagle can’t. Each open library is a workspace with all of its own state: where you are (scope, back and forward history, search, filters, sort and layout), the selection, the viewer, its undo and redo stacks, open dialogs and its image caches. Switching keeps all of it. Global state stays shared: Preferences, shortcuts, the recent list, zoom, panel visibility, the collect window and the HTTP API server.

• Switching: click the library name at the top of the sidebar or press ⌘L. The menu lists the open libraries first (name over its folder, dimmed, the shown one highlighted, × to close), then recent libraries that aren’t open, then Open Library…, New Library…, Show in Finder, the collect window and Preferences. ⌃⇧Tab and ⌃Tab step through the open libraries.
• Opening a library that is already open shows it instead of loading it twice (paths are compared after resolving symlinks). A new workspace starts with the shown library’s sort and layout and is added at the end of the list.
• The loading screen appears while a library is read on a background thread: one chosen in the switcher, with Open Library… or dropped on the window, the libraries reopened at launch, one just created, and the missing-library screen’s Try Again and Select Another Path…, so a large library doesn’t freeze the window. It shows “Opening ” with a progress bar and a line that reads “Reading the library…” while the item folders are being listed, then “Reading items: 50 of 200”, then “Almost there…”. It fills the window when no library is open and is a dialog over the shown library otherwise. Only one library loads at a time; others wait their turn in a queue (app/open_queue.rs), and the install-folder check and backup restore run on that thread. When it finishes the library appears in a workspace of its own. At launch, the library shown before quitting (or the one given on the command line) is shown once all are read, and the command line’s items, search, colour, tags page, imports and links, as well as links and files opened with falcon meanwhile, wait until then. Try Again on a folder that is still missing says so at once without a load; a path picked with Select Another Path… replaces the old one in the recent list once it has opened.
• Storage warnings come from a check run once on a background thread when a library opens (crates/falcon-app/src/storage.rs), after Eagle’s warnings. It tries to open metadata.json for appending, creates and removes a <ms>.tmp folder in the library, times that round trip, and asks macOS for the volume type. A read-only metadata.json or a folder where nothing can be created gives a “ may not save changes” alert, with the reason and a hint to check permissions or move the library. A round trip slower than 1.5 s (falcon’s own threshold, since Eagle’s isn’t in its readable source) or an NTFS volume gives a toast instead, saying the disk is slow or that NTFS drivers on macOS are slow and less reliable and that APFS or exFAT works better.
• Outside changes are picked up while a library is open. Each workspace polls the library’s metadata.json and mtime.json every 4 seconds on its own thread (crates/falcon-app/src/watch.rs; see the library format). A newer metadata.json replaces the folder tree, and the undo and redo history and any open folder edit are cleared since they no longer fit it. Items added, edited or deleted elsewhere appear, change or go, and the thumbnail cache forgets the ones that changed, and an item open in the editor that changed is closed. Falcon’s own saves cause no change. This covers libraries that aren’t shown as well as the one on screen.
• A library whose folder vanishes (moved, renamed, deleted or its drive ejected) closes without the flush and backup a normal close does, because those writes would fail or recreate files in the old place. Pending writes are discarded, and the missing-library screen opens for it.
• The missing-library screen is titled “Library not found” and names the path: there is no library folder there, and it may have been moved, renamed or deleted, or its drive isn’t connected. It appears when opening a library whose folder doesn’t exist (a recent entry marked missing, or a path passed in), when a library’s folder vanishes while it is open, and at launch when the library that was shown when falcon quit is gone (a hidden library that is gone is only skipped, as before). It fills the window when no library is open and is a dialog with an extra Close button otherwise. Try Again opens the same path again and flashes “The library is still missing” if it is still gone. Select Another Path… opens a folder picker and, when a library opens from it, removes the old path from the recent list. “Can’t find it? Create a new library” opens the Create a Library dialog.
• Merge Another Library… asks for a folder, then shows “Merge into ?” with what would come in and Merge and Cancel buttons. The open library itself, a folder with no metadata.json and a library from a newer Eagle are refused with a “Can’t merge that library” alert. Merge copies the missing item folders on a background thread behind a “Merging ” dialog that can be cancelled, then merges the folder tree. A Merge finished alert gives the numbers of items, folders and smart folders or tag groups added. If the items were copied but the folders couldn’t be saved, a Merge not finished alert says so. The rules are in Merging libraries.
• Empty Cache and Reload… asks “Empty cache and reload?” (Empty Cache and Reload or Cancel). On confirming, falcon writes what is pending, reads the shown library from disk again (restoring a backup if metadata.json is damaged), rebuilds its mtime.json from the items, drops every decoded thumbnail and preview, and flashes “Library reloaded”. A large library takes a while. If the save before it fails, nothing is reloaded.
• Import Eagle Package… asks for an .eaglepack and reads it without extracting it (see Export). A dialog says how many items the package holds and how much disk space they take in this library, with Import and Cancel. When some look like items already in the library, a second dialog, titled with their count (“3 items already in the library”), asks whether to import them anyway: Import brings everything in, Leave Them Out imports the rest (Eagle’s Don’t Import), and closing the dialog with Esc imports everything, as dismissing Eagle’s does. The import then runs behind a progress modal with a count of items and a Cancel button; Cancel stops before the next item and the items already imported stay. A file that isn’t a readable package gives a “Can’t import the package” alert. A package picked here goes into the open folder if one is open. Dropping an .eaglepack on the window does the same, and one dropped on a folder goes into that folder. Only the first package of several dropped files is taken, and the other files import as usual.
• Import Inboard Backup… asks for a backup folder. A folder without InboardBackup.json gives a “Not an Inboard backup” alert. Otherwise one top-level folder is created for each Inboard folder and the images import in the background with their names, tags, links, trashed state and dates, and a toast reports “Importing images and folders from Inboard”, with the number of files missing from the backup. The format is in Inboard backups.
• Creating a library (New Library… in the switcher) opens the Create a Library dialog. Enter a name (not empty, none of @ # $ % ^ & * < > : ' " / \ | ?; at most 127 characters) and press Create or Return; Esc cancels. A system dialog then asks which folder to keep the library in, starting in the folder that holds the shown library. A folder whose path contains “Desktop” or “Downloads” brings a warning that a library there risks being deleted by accident, with Choose Another and Save Anyway. The library is made as <folder>/<name>.library and opened. If one already exists there the dialog stays open with a message so another folder or name can be tried. The code is in crates/falcon-app/src/ui/dialogs/library.rs.
• The welcome flow replaces the empty window on a first launch, when no library has ever been open or recent. It has three steps with Back and Next and a row of dots: a title with a one-line description, a choice of theme (shown as swatches, applied at once and saved with the preferences), and a name field with a few example names, a Create Library button and an Open Existing Library… link. Create Library checks the name as the Create dialog does and continues with the folder choice and the Desktop and Downloads warning; cancelling the folder choice stays on the step. Once any library is opened or created, the flow is marked finished in the saved state and never returns; a launch that finds saved libraries skips it. If a library failed to open at launch, the plain empty window with the error is shown instead. After the flow, and when the last library is closed, the empty window shows the title, the error if there is one, a Create Library button (opens the Create dialog) beside an Open Library button (picks an existing library folder), and a line saying a library is a folder that holds your files and their tags.
• Closing writes the library’s pending changes, then picks the next library to the right (or the left at the end). Closing the last one leaves the empty window and stops the API.
• Switching while tasks run: switching to another library never stops anything, since a library in the background keeps importing and finishing its operations, but leaving a library that has imports in flight, a long operation behind the progress modal, an export or an AI step in Actions running asks first. “Switch Library While Tasks Run” names the library and says the tasks keep running in the background, with Force Switch and Cancel (Escape or a click outside also cancel); if the tasks finish while it is up, the switch goes ahead. It guards the switcher’s rows, ⌃Tab and ⌃⇧Tab, recent libraries, Open Library… and a dropped library (once the folder is known), New Library… (before its dialog) and the HTTP API’s library/switch. The API’s library leaves the shown workspace at once, before the question, so running tasks never write to it; Cancel keeps the API on the shown library and a message says so.AI runs count as tasks and keep running after a switch, where Eagle blocks the switch.
• Closing while tasks run: closing a library does stop its tasks. When the library has imports in flight, a long operation behind the progress modal, an export or an AI step running, the × asks “Close Library While Tasks Run”: tasks are still running in , closing stops them, and work already done is kept. Stop Tasks and Close tells the import to skip the files it hasn’t started (they count as done, so the batch ends) and the progress modal’s operation (an export included) to stop before its next item, cancels an AI step’s request, and shows “Stopping tasks…” with no buttons. The library closes, with the usual save and backup, only once every worker has stopped, so nothing writes to it after that save. Cancel leaves everything as it was. The pending close is kept by the library’s folder, since switcher positions shift (crates/falcon-app/src/ui/dialogs/force_close.rs).
• Quitting while tasks run: the same warning guards quitting, since a quit would cut off imports, a progress-modal operation, an export or an AI step in any open library, the one shown or one in the background. Quit asks “Quit While Tasks Run” (tasks are still running, quitting stops them, work already done is kept) with a red Stop Tasks and Quit and a Cancel (Escape or a click outside also cancel). Stop Tasks and Quit stops the tasks of every library as above, shows “Stopping tasks…” until the workers have stopped, and then closes the window for real, so the usual save and backup on quit run. With nothing running, Quit quits at once. It asks from ⌘Q and the app menu’s Quit (falcon replaces winit’s Quit item, which ended the process, with one that asks the app), the menu bar icon’s Quit Falcon (which also brings the window forward so the question is seen), and a window close that would quit (the Dock option off with no menu bar icon). A close that only hides the app never asks. Quitting from the Dock icon’s own menu, or by logging out, is AppKit calling terminate directly, which falcon cannot intercept without replacing winit’s application delegate, so it does not ask (crates/falcon-app/src/ui/dialogs/quit_confirm.rs).
• Window title: the shown library’s name (“Falcon” when none is open). The title bar is hidden, so it shows in the Window menu, Mission Control and the Dock.
• Launch: the open libraries, and which one was shown, are saved with the app state (libraries and active) and reopened; a missing one is skipped, except that when the library that was shown is gone the missing-library screen opens for it. A library passed on the command line is opened (or shown, if it was already open) after them. State saved by older versions, which has only library, opens that one library.
• API warnings: two problems with the local API show a “Local API unavailable” alert, which stays until dismissed or until the API is restarted. When no port of the range is free (another program answers on each), it reads that the API couldn’t start, names the ports, says apps and browser extensions won’t reach it and points to the first port in Preferences ▸ Developer. About a second after the server starts, a background thread resolves localhost and tries a plain connection to each loopback address on the server’s port (crates/falcon-app/src/api_check.rs; no HTTP request is made, and never to port 41595). If none connects, the alert says the API runs on that port but can’t be reached through localhost, so browser extensions can’t reach Falcon, and that a proxy or VPN may be redirecting localhost. A working start still only flashes “API on http://localhost:”.
• HTTP API: it serves the shown library and keeps its port when you switch. A library/switch request opens (or shows) that library in its own workspace and gives the one it replaced back its library; see HTTP API.

What Eagle does (Eagle 4.0, from js/directives/library-panel.js and its template, js/background.js, js/api-server.js and js/default-preferences.js; observed unless marked):

• One library per window. The renderer keeps a single library path, and switching (openLibrary, then the add-to-history-and-open message to the background page) saves the cache, drops the current library and loads the new one in the same window. A dialog first asks to cancel running imports, downloads or saves. No code path opens a second main window for another library (inferred from the absence of one; the main-process window code isn’t in the extracted renderer files).
• The library panel opens at the brand icon (switchLibrary) or with library.switch, ⌘L by default. It has a search field (fuzzy, with pinyin), then one row per entry of the libraryHistory setting: the library’s icon (icon.png in the library, if any), its name without .library, its parent folder, and a check on the open one. Rows can be reordered by dragging, and their menu changes or removes the icon, shows the library in Finder, or removes it from the list. Below the list: Create, Load (open), Reload and Merge. ↑, ↓ and ↩ pick a row; Esc closes the panel.
• libraryHistory appends a newly opened library at the end, without duplicates, and keeps the user’s order. A separate pinnedLibrary list exists.
• Item counts are not shown in the panel.
• library/switch over the API calls the same openLibrary, so the API always serves the window’s library.
• Eagle has no next or previous library shortcut; library.create and library.load exist without defaults.

How falcon differs: several libraries open at once (above) and its own ⌃Tab and ⌃⇧Tab shortcuts; one window rather than one OS window per library (Eagle doesn’t have several windows either); the recent list is newest first and capped at 10, with no search, pinning or reordering yet. It has icons, Merge Another Library… and Empty Cache and Reload… (Eagle’s Merge and Reload).

Layouts and display options

The toolbar’s layout button opens a panel after Eagle’s (layout-panel.html, seen), in its order: the layout; for the Grid layout, the fill mode (Fit shows the whole image, Fill crops it to fill the square); the Thumbnail option (Speed or Quality, Quality by default as in Eagle’s eagle.list.show.originalImageWhenLarge: a jpg, png, webp, bmp or jfif card drawn larger than its 512 px grid render shows its original instead, decoded on the loader’s workers at up to 1600 px into a cache of 16, about 160 MB at most, after the visible thumbnails; originals still in iCloud aren’t downloaded for it. Eagle swaps once its tile height passes 600 px, which falcon’s 400-point tiles never reach, so falcon asks whether the card would otherwise be enlarged); the sort, with the direction (inside a folder or smart folder, that view’s own sort, as in the folder menu); the switches Show Name, Show Item Info (with what the info line shows: Dimensions, File Size, Tags, Rating, Date Modified or Date Created), Show Extension (at the end of the name), Show Extension Label (the type badge), Show Comment Count, and Show Subfolder Content; Show Sidebar and Show Inspector; and Refresh, which writes anything pending, reads the library again from disk, decodes the thumbnails again and reshuffles random orders. The panel stays open while you flip switches; a click outside closes it. A right-click on empty grid space (in any layout, and on the empty view; not on a card, the subfolder cards or the list header) opens the same panel at the pointer, as in Eagle, and leaves the selection alone. The code is in crates/falcon-app/src/ui/toolbar/layout_panel.rs, the rules in logic/.

Selection

Click selects one item, ⌘-click adds or removes one, ⇧-click selects the range from the last clicked item, and a click on empty space clears the selection.

Dragging over empty grid space draws a rubber band, in every layout, as Eagle’s rect-select does (seen): every card the band touches is selected, replacing the selection; with ⌘ held when the drag starts, each touched card flips (selected ones drop out); with ⇧, touched cards join the selection (Eagle keeps the selection when a ⇧ drag starts but drops what the band leaves as it moves, so ⇧ acts nearly like a plain drag there; falcon adds, as Finder does). Shrinking the band gives back what it no longer touches. Held within 24 px of the grid’s top or bottom edge (or past it), the band scrolls the grid. A drag that starts on a card still drags items. The rules are logic::marquee_selection and logic::rect_hits.

⇧→ and ⇧← extend the selection one item at a time, as Eagle’s multiple select does: the selected run grows at its end away from the anchor (the item last clicked or moved to), and shrinks back toward the anchor when it already reaches past it on the other side. ⇧↓ and ⇧↑ do the same in the List layout; in the other layouts they do nothing, as in Eagle (logic::extend_selection).

When the selected items leave the grid (moved to the Trash, restored or deleted from the Trash, removed from the open folder, or dragged onto another folder, which moves them out), the item after them is selected, or the one before at the end of the grid, as Eagle does. Items dragged into a subfolder the view shows (with Show Subfolder Content on) stay selected.

Hover preview

Hovering a card shows a faint zoom button in the bottom-right corner of its image (in the List layout, over the whole thumbnail). Resting on the button for 200 ms floats an enlarged copy of the image over the window, which dims behind it. Holding Z shows it at once for whichever card is under the pointer. The code is in crates/falcon-app/src/hover.rs.

What Eagle does, from its js/hover-preview.js, style/components/_hover-preview.scss and _box-container.scss:

Video and audio hover playback

From Eagle’s js/hover-preview/video-hover-preview.js and audio-hover-preview.js. Falcon’s state, rules and worker are hover_media.rs, the drawing ui/grid/hover_media.rs. It works in every layout (Grid, Waterfall, Justified and List) and on every page that lists items (folders, tags, smart folders, search, All): they all draw their cards in the one grid loop. In the List layout the preview fills the row’s thumbnail square, with the progress bar only (the speaker button and time pill would cover a square that small; the choice is kept, and a click on an audio row’s thumbnail still seeks).

Tests: the state machine (delay, scrub mapping, rest and resume, loop, leave ends the preview in its frame, the sound plan) is in hover_media.rs, the toggles’ persistence in logic/display.rs, and the decoders per container in falcon-library/src/audio/tests.rs. The Matroska and WebM cases need the FFmpeg libraries: run them with FALCON_FFMPEG_DIR=<path>/target/ffmpeg/lib, else they only check that the open fails with the reason.

Preferences

⌘, (or Preferences… in the app menu) opens a window over the main one, laid out like Eagle’s: a search box above the list of panes on the left, the pane on the right, and Save, Apply and Cancel at the bottom. The panes follow Eagle’s order, with separators between groups: General, Sidebar | Controls, Preview, Screenshot, Shortcuts | Notification, Password, Auto-Import | AI Search, AI Models, Eagle MCP | Developer. Eagle’s Proxy pane is not built; a pane appears only once it has a working setting. Each pane is one function in crates/falcon-app/src/prefs.rs that adds titled blocks to a Page.

Typing in the search box shows the matching blocks of every pane under the pane’s name. A block matches when every word typed appears in the pane name, the block title or its keywords (case-insensitive), as Eagle’s blocks carry keyword lists. The Shortcuts pane appears in the results as a button that opens it. The last pane shown is remembered across launches, as Eagle remembers it.

Edits stay in a draft until Save (also ⌘↩) or Apply; Cancel, the close button and Esc drop them, as in Eagle. A previewed theme, interface zoom or language reverts on Cancel. The values are saved with the rest of the app state.

One Eagle setting has no counterpart in falcon: GPU acceleration, because falcon always draws with wgpu (eframe’s glow backend is not compiled in, and the 3D viewer needs wgpu), so there is nothing to switch to. Color Space is in the App menu (see above) and sets the window’s CAMetalLayer colour space; falcon’s pixels are still sRGB content.

What Eagle does, from js/default-preferences.js, preferences.html, js/preferences.js and css/preferences.css (all seen):

• Preferences live in one tree with groups general, habits, shortcuts.keybinds, theme, notification, sidebar, screencapture, video, proxy, privacy, autoImport and developer. Booleans are stored as the strings 'true' and 'false', and choices as strings (hoverZoom: "on").
• The window’s sidebar (200 pt wide, 32 pt rows) has General and Sidebar, then Controls, Preview (the habits group), Screenshot and Shortcuts, then Notification, Password and Auto-Import, then the AI panels. A search box filters every panel by keywords.
• Save applies and closes, Apply applies and stays open, Cancel and Esc revert (including a previewed theme or zoom), ⌘↩ saves.
• The window’s own size is set in Eagle’s main process, which is not in the readable bundle; falcon’s 720 × 500 pt is a guess (inferred).
• Built in falcon since: the menu bar icon option, the collect modal for screenshots, and screenshots with their keys, format, quality, tag, clipboard and @2x settings.
• Built in falcon since: sound effects (see below).
• Not built in falcon: GPU, proxy.