docs: ADR 0094 portable mode and AppImage desktop integration; guide, packaging README, roadmap, changelog (M8)

This commit is contained in:
Tanish Manku committed 2026-11-13 22:57:11 -07:00
1 parent 60aa9a6943
commit 463c4fcfad
8 files changed
+205 -4

No files matched your search

+1
View File
@@ -87,6 +87,7 @@ OR Apache-2.0) is noted in the table.
| Hairlines: coverage falling off with the distance from the pixel centre to the line | `crates/render/src/hairline.rs`, `crates/gpu/src/fine.wgsl` | S. Gupta and R. F. Sproull, *Filtering Edges for Gray-Scale Displays* (SIGGRAPH 1981): anti-aliased lines by distance; standard | Public method; a one-pixel tent filter of the distance (ADR 0048). |
| Plural categories for whole numbers (zero, one, two, few, many, other) | `src/i18n/plural.rs` | Unicode CLDR, *Language Plural Rules* (`common/supplemental/plurals.xml`), <https://cldr.unicode.org>, Unicode License v3 (Unicode-3.0) | The integer rules rewritten as Rust `match`es from the published rules; no CLDR data file is bundled. |
| Stage elements as a multi-select list box; menu bar keyboard model (Alt/F10, arrows, access keys) | `src/stage_a11y.rs`, `src/menus.rs` | W3C *WAI-ARIA Authoring Practices Guide*, Listbox and Menubar patterns, <https://www.w3.org/WAI/ARIA/apg/> (W3C Software and Document License) | Keyboard behaviour learned from the published patterns; no code or text copied. |
| Desktop integration of an AppImage: desktop entry `Exec` quoting and string escapes, MIME packages, hicolor icons, the user's data folder | `crates/engine/src/cmds_desktop.rs`, `src/platform.rs` | freedesktop.org *Desktop Entry Specification* 1.5, *Shared MIME-info Database*, *Icon Theme Specification*, *XDG Base Directory Specification*, <https://specifications.freedesktop.org/>; AppImage documentation on `$APPIMAGE` (public docs) | Written from the specifications (ADR 0094); no code copied. |
| Reading the desktop's contrast setting | `src/platform.rs` | *XDG Desktop Portal*, Settings interface, `org.freedesktop.appearance` `contrast` key, <https://flatpak.github.io/xdg-desktop-portal/> (LGPL documentation, read only; nothing bundled or linked) | One value read through the `gdbus` tool. |
| Interface catalog format (TSV keyed by English, `@plural`/`@id` rows, fallback order) | `src/i18n/catalog.rs`, `build.rs` | storytold/craft-i18n `docs/catalog-format.md` and `docs/integration.md` (MIT OR Apache-2.0, same project family) | Our own parser written from those documents; the craft-libs `craft-i18n` crate is not used (ADR 0040). |
| Adaptive Bézier flattening (Wang's formula) | `crates/geom/src/path.rs` | G.-J. Wang (1984); public mathematical result | |
+17
View File
@@ -2,6 +2,23 @@
## Unreleased
* **Portable copies and AppImage desktop integration** (ADR 0094, M8).
* **The Windows zip and the Linux tar.gz are portable**: preferences, autosaved work, logs,
plug-ins, templates, brushes, filter presets, workspaces and recent files stay in a `data`
folder beside AniCraft. A file named `anicraft-portable` next to the program (or next to
`AniCraft.app` or an `.AppImage`) is what makes a copy portable; delete it to use your user
folder. A portable folder that can't be written falls back to your user folder and says so.
* **Preferences › About** shows the version, whether this copy is installed or portable, and
every folder AniCraft keeps things in, each with an Open button.
* **AppImage: Add to Menu.** The first start from an AppImage offers once, in a card that
nothing waits on, to add AniCraft to your applications menu and open `.anicraft`, `.fla` and
`.xfl` files with it. Only `~/.local/share` changes; Preferences › About removes it again,
and the entry follows the AppImage when you move or update it. Headless:
`desktop.integrate`, `desktop.remove`, `desktop.status`.
* **Store readiness:** a Packaging lint job validates the Flatpak manifests, the AppStream
metainfo (`appstreamcli validate`), the desktop entry and any winget or MSIX manifests.
Nothing is submitted.
* **Brushes and erasing, second slice: tilt, textured brushes, erasing inside symbols, profiles
in the merge** (ADR 0093, M7).
* **Pen tilt** shapes the Brush: it turns the tip with the way the pen leans and paints up
@@ -0,0 +1,108 @@
# ADR 0094: Portable mode and AppImage desktop integration
* Status: accepted (2026-11-13)
* Relates to: roadmap M8 (installers), ADR 0026 (packaging layout), ADR 0062 (opening documents
from the OS), ADR 0015 (autosave), ADR 0059 (recent files), ADR 0004 (destructive actions),
ADR 0006 (cross-platform)
## Context
ADR 0026 shipped a Windows portable zip and a Linux tar.gz that still kept their settings in the
user's profile, and an AppImage that nothing adds to the applications menu: double-clicking a
`.anicraft` did nothing until the user wrote a `.desktop` file by hand. Artists carry their setup
between studio and home machines on a stick, and an AppImage user expects the app to offer to
integrate once, as AppImageLauncher-style tools do. App stores (Flathub, winget, the Microsoft
Store) reject metadata errors at submission time, which is late.
## Decision
1. **One switch for every folder.** `platform::placement()` decides once, at first use, whether
this copy is portable; `config_dir()` returns the portable data folder when it is, and every
other folder (preferences, `Recovery`, `Logs`, `plugins`, `Templates`, `Thumbnails`) already
hangs off `config_dir()`. Recent files, brushes, filter presets and workspaces are in
`prefs.json`, so they follow. The offline user guide goes to `data/Cache`. The environment
overrides (`ANICRAFT_RECOVERY_DIR`, `ANICRAFT_LOG_DIR`, `ANICRAFT_TEMPLATES_DIR`) still win.
2. **A marker file, not a guess.** A copy is portable when a file named `anicraft-portable`
(contents ignored) is found: next to the program; above `bin/` (the tar.gz layout); next to
`AniCraft.app` on macOS (never inside the bundle, which would break its signature); next to the
`.AppImage` (`$APPIMAGE`), not inside its read-only mount. Data goes to `data/` beside the
marker. The Windows zip and the Linux tar.gz ship the marker; the MSI, DMG, deb, rpm, Flatpak
and Arch package never have one (the Flatpak and Arch builds copy only `bin/` and `share/` from
the tarball, checked in the shared workflow's scripts). Guessing from the install location
(Program Files, `/usr`) was rejected: it misfires on custom install folders and can't be
switched off by the user, whereas deleting the marker can.
3. **Unwritable portable folders fall back, visibly.** If `data/` can't be created and written (a
probe file), the user folder is used and Preferences › About says why, rather than running
with settings that silently never save.
4. **Desktop integration is engine commands.** `desktop.integrate {appimage, data_home}`,
`desktop.remove {data_home}` and `desktop.status` (`crates/engine/src/cmds_desktop.rs`) so the
CLI and MCP can do it too. They write exactly: `applications/ai.storyteller.anicraft.desktop`
(the packaged entry with `Exec`/`TryExec` pointing at the AppImage and an `X-AniCraft-AppImage`
key marking it as ours), `mime/packages/ai.storyteller.anicraft.xml` (the packaged MIME types)
and the hicolor icons (16–256 px and the SVG), then run `update-mime-database` and
`update-desktop-database` when installed (bounded to 5 s each, output ignored). The packaged
desktop and MIME files and the icons are compiled in from `packaging/linux` and
`assets/app-icon`, so there is one source.
* The entry keeps the app id as its file name, so Wayland docks match the running window
(`app_id`) to it. It shadows a system package's entry while present; removing it brings
that one back.
* `Exec` quotes the path as the Desktop Entry Specification says (always double quotes;
`"`, `` ` ``, `$`, `\` escaped; `%` doubled; then string-value escaping), so spaces, quotes
and dollar signs in folder names work. Paths with line breaks or that aren't UTF-8 are
refused.
* **Never system folders:** `data_home` must be absolute and outside `/usr`, `/etc`, `/opt`,
`/var`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/boot`, `/snap`. The desktop app passes
`$XDG_DATA_HOME` (a relative one is ignored, per the XDG Base Directory spec) or
`~/.local/share`.
* **Idempotent and safe to undo:** writing again rewrites only files that differ (temp file +
rename); removing deletes only our file names, and nothing at all when the entry there
wasn't written by AniCraft (no marker key), which `integrate` also refuses to replace.
* Plug-ins may not call `desktop.*` (`plugin_may_call`).
5. **Offered once, never modal.** On the first start from an AppImage (not portable, no entry
yet) a card at the bottom right asks "Add AniCraft to your applications menu?" with **Add to
Menu** and **Not Now**. Either answer is kept (`desktop_offered` in the preferences); editing
never waits on it. Preferences › About has Add / Remove / Use This Copy at any time. An entry
that points at an AppImage which no longer exists (moved, or replaced by an update) is
re-pointed at the running copy without asking: the user already said yes. Adding or removing
is a routine, reversible edit of the user's own folder (ADR 0004): no confirmation.
6. **Store readiness is a check, not a submission.** `packaging/check-store-readiness.sh` runs in
Packaging lint (`store-readiness` job, Ubuntu with `appstream`, `desktop-file-utils` and
`python3-yaml`): both Flatpak manifests parse, carry the app id, command and required keys,
agree on runtime, SDK and permissions, and ask for no `home`/`host` file system access; the
filled-in AppStream metainfo passes `appstreamcli validate --no-net`; the desktop entry passes
`desktop-file-validate`; winget and MSIX manifests, when the team adds them under
`packaging/windows/{winget,msix}`, have their required fields. Errors fail; a missing tool is
a warning, so the script also runs on a laptop.
## Consequences
* A zip or tarball unpacked to a stick keeps everything on the stick. Existing users of the zip
start with fresh preferences in `data/` (their old ones stay in `%APPDATA%\AniCraft`); the
guide says how to copy them over or delete the marker.
* AppImage users get a menu entry and file associations with one click, and lose them with one.
* The engine and CLI carry about 270 KB more (the icons and two text files).
## Not in this slice
* Making `mimeapps.list` name AniCraft the default for `.anicraft` (it is the only handler, so
desktops pick it anyway); `.fla`/`.xfl` stay "Open with" as in ADR 0026.
* Self-update inside a portable copy (craft-update keeps its own state folder) and moving
existing settings into a new portable copy.
* Submitting to Flathub, winget or the Microsoft Store, and committing winget/MSIX manifests.
* Running `flatpak-builder-lint` (needs the Flathub tooling on the runner).
## Alternatives considered
* **The sibling apps' `AppRun` shell script that integrates on every start.** Rejected: it writes
without asking, can't be undone from the app, and runs before the app can show anything.
* **A different desktop file name (`appimagekit_<hash>-anicraft.desktop`).** Rejected: the window
would no longer match its launcher on Wayland, and the dock would show a generic icon.
* **Detecting portable from the install path.** See decision 2.
## References
* freedesktop.org *Desktop Entry Specification* 1.5 (Exec quoting, string escapes, `TryExec`,
`X-` keys), *Shared MIME-info Database* 2.4, *XDG Base Directory Specification* 0.8, *Icon Theme
Specification* (hicolor), *AppStream* metainfo; AppImage documentation on `$APPIMAGE` and
desktop integration; winget manifest schema 1.6 and the MSIX `AppxManifest` schema (public
docs). No code copied.
-1
View File
@@ -23,4 +23,3 @@ has to renumber because another PR merged first.
| Number | Pull request | Topic |
|---|---|---|
| 0037 | #38 (outside contribution) | Interface languages |
| 0094 | m8/portable-and-desktop | Portable mode and AppImage desktop integration |
+25
View File
@@ -24,6 +24,31 @@ files show AniCraft under "Open with", but your default app for them doesn't cha
command-line tool, `anicraft-cli`, is installed alongside the app (see
[Working headless](working-headless.md)).
### Running the AppImage
The first time you start AniCraft from an `.AppImage`, a small card at the bottom right offers to
**Add to Menu**. Say yes and AniCraft appears in your applications menu with its icon, and
double-clicking a `.anicraft`, `.fla` or `.xfl` file opens it. Only your own data folder
(`~/.local/share`) changes; nothing is installed for other users. **Not Now** puts the card away
for good. Either way, **Preferences › About** has the button to add AniCraft to the menu or
remove it again. If you move the AppImage or an update replaces it, the menu follows the copy
you start next.
### Portable copies
The Windows `.zip` and the Linux `.tar.gz` are **portable**: they keep your preferences,
autosaved work, logs, plug-ins, templates, brushes, filter presets, workspaces and recent files
in a `data` folder beside AniCraft, not in your user folder. Unpack one onto a USB stick and
your setup travels with it. A file named `anicraft-portable` next to the program is what makes a
copy portable: delete it to use your user folder instead, or put one next to an `.AppImage` or
next to `AniCraft.app` on a Mac to make those portable too. If the `data` folder can't be
written (a read-only disc, say), AniCraft uses your user folder and says so. To bring your
existing settings along, copy the contents of your user settings folder (Preferences › About
shows it in an installed copy) into the portable copy's `data` folder.
**Preferences › About** shows which kind of copy you are running and every folder it uses, each
with an **Open** button.
There is also a web version that runs in a modern browser. It can't play sound, export video
or install plug-ins yet, and menu items that can't work there are dimmed and say why.
@@ -73,6 +73,14 @@ Preferences.
* **Safety › Confirmations**: if you ticked "Don't ask again this session" in a confirmation,
**Show all again** brings those questions back.
### About
**About** shows AniCraft's version, whether this copy is installed or portable (see
[Portable copies](getting-started.md#portable-copies)), and every folder it keeps things in
(preferences, autosave, logs, plug-ins, templates and the offline user guide), each with an
**Open** button. Run from an AppImage on Linux, it also adds AniCraft to your applications menu or
removes it again.
Preferences also keep your shortcuts, onion skin options, Publish presets, recent files and
whether the start screen shows. The start screen has its own checkbox: **Show this screen when
AniCraft starts**.
+3 -3
View File
@@ -22,7 +22,7 @@ milestone ends with a green tree: build, tests, clippy, a `--screenshot` check a
| Tests | 133 tests (adds point editing, closed-path anchors, curve fitting, pen/pencil/subselection commands, the Pen's path data, frame ranges, keyframe moves, range confirmations, frame selection and the frame clipboard): unit, analytic render, band/determinism, robustness fuzz over all commands, round trip (v1 and v2 files), structural sharing and history budget, render-service equivalence, confirmations, clipboard, transforms and align, GIF decode and timing, free-transform maths, UI-guideline enforcement, CLI. |
| Ease of use & safety | **Visual language** (ADR 0008, revised): graphite palette, corners by role (square structure, softened controls, rounder menus and dialogs with soft depth), borders only between layout regions, flat buttons with a visible focus ring, vibrant timeline blocks (mint artwork, violet tweens), sentence-case headings, **collapsible sections with rules** (Preferences, Properties, dock, shortcut sheet), **Lucide icons** stroked as vectors via a new full SVG path reader; click targets ≥ 28 px (tools 40, rows 28, toggles 24); palette contrast, target sizes and "no raw colours or radii" are enforced by tests. Product principles written (`docs/product-principles.md`). Tiered destructive-action confirmations, enforced in the engine (ADR 0004). Unsaved-changes guard on close/new/open. **Crash-recovery autosave** (ADR 0015): unsaved work is copied in the background (every minute or 25 changes by default; Preferences › Files › Autosave, with an off switch) to `Recovery` in the settings folder, atomically and never over the user's file; an OS file lock per running window tells crashed sessions from open ones; the next start offers what was left behind in a non-blocking window (Restore as unsaved work with its original path, Discard with a second click, Later; File › Recover Autosaved Documents… brings it back); saves and clean exits remove the copy; headless `file.recovery_list/recover/discard_recovery/autosave`. Not yet: several open documents, older copies, the undo history. Overwrite checks for saves and exports. "Ctrl+Z to undo" hints. Command palette (Ctrl+K). Shortcut sheet (F1). Right-click menus on stage, frames and layers. Save As (Ctrl+Shift+S). **Shortcut editor** (F1): every menu command, tool and view key can be rebound, given extra keys or unbound; recording asks before taking a key from another action, reserved keys (palette, editor, Preferences, quit, play, Esc, Space, Tab) stay fixed, per-action and global reset; only the changes are saved in preferences, so untouched actions follow new defaults; menus, tooltips and the palette show the keys in effect. |
| Platforms & preferences | ADR 0006 platform layer: ⌘ shortcut labels and an AniCraft app menu with a unified title bar on macOS; Exit and Preferences (Ctrl+U) on Windows and Linux; native file dialogs (XDG portal on Linux, with a fallback switch); wgpu with automatic OpenGL fallback; per-OS settings folder. **Web editor, first slice** (ADR 0036, `docs/web.md`): the same program built for `wasm32-unknown-unknown` runs in a browser (WebGL2), built by `scripts/build-web.sh`/`.ps1` with the wasm-bindgen CLI into `web/` (8973 KB, 3278 KB gzipped). Open and import with the browser's file picker; save and export as downloads (the engine reads and writes through `engine::vfs`, memory in the browser). Autosave and preferences in browser storage, with Web Locks so only closed or crashed tabs' work is offered. Leaving with unsaved work asks first. Every crate builds for wasm32 in CI, and the engine's tests run inside WebAssembly in Node. Not yet: a browser-verified run, sound (Web Audio), the GPU stage on WebGPU, video export, plug-in installs, PNG sequence as one zip, IndexedDB for large autosaves, threads, hosting. **Preferences** window: theme (Follow system, Dark (Graphite), Light or High contrast; ADR 0077), interface and data fonts (bundled default or any installed font), interface scale (75–200 %), stage render mode, file dialogs, reset confirmations. Edits render live (fixed the missing-repaint bug). **CI on macOS and Windows** (ADR 0067): every code PR builds, tests and lints the workspace on macOS (arm64) and Windows (x64) runners besides Linux. Not yet: native macOS NSMenu, Linux arm64 and Windows ARM64 test legs on PRs, a GPU runner. Verified by hand on Windows only so far. **Robust start-up** (#207): the window opens through a list of ways (the one chosen in Preferences › Stage › Window graphics or `--renderer gl|wgpu|vulkan|dx12|metal`, then wgpu automatic, DirectX 12 on the low-power GPU on Windows, OpenGL), falling through on an error or a panic; a start that died inside a driver tries that way last next time; a start-up log (`Logs/anicraft.log` in the settings folder, the previous run's kept) records each way, the adapter and driver, panics and slow starts; a system message names it when nothing works. Not yet: verified on a hybrid-GPU laptop, the log from the Help menu. |
| Installers & release | **Packaging** (ADR 0026, `docs/release.md`): the Craft family's `packaging/` layout behind the shared release workflow. Windows MSI (x64, arm64; per-user by default, everyone on request, upgrades in place), portable and symbols zips; macOS universal DMG with a laid-out window and CLI zip; Linux AppImage, deb, rpm, tar.gz, Flatpak and Arch (x86_64, aarch64; riscv64 deb/rpm/tar). `.anicraft` opens AniCraft by default; `.fla`/`.xfl` offered under Open with. Signed and notarized on the `release` branch (missing secrets fail it), unsigned elsewhere; ends in a draft release. Packaging lint and a fixture WiX build guard PRs; `src/packaging_tests.rs` keeps ids and types in step. **Opening documents on macOS** (ADR 0062): a double-click in Finder, a drop on the Dock icon or Open With opens the document, at launch or while running (the open-documents Apple Event through `platform.rs`, by `fmv-macos-events`, so no `unsafe` of ours), through the unsaved-changes guard; the Dock's Quit asks to save too; Windows and Linux command-line hand-over covered by a test. Not yet: verified on a Mac (the checklist is in ADR 0062), a single running AniCraft taking a second document on Windows and Linux, AppImage desktop integration, portable mode, store listings, video export inside the Flatpak. |
| Installers & release | **Packaging** (ADR 0026, `docs/release.md`): the Craft family's `packaging/` layout behind the shared release workflow. Windows MSI (x64, arm64; per-user by default, everyone on request, upgrades in place), portable and symbols zips; macOS universal DMG with a laid-out window and CLI zip; Linux AppImage, deb, rpm, tar.gz, Flatpak and Arch (x86_64, aarch64; riscv64 deb/rpm/tar). `.anicraft` opens AniCraft by default; `.fla`/`.xfl` offered under Open with. Signed and notarized on the `release` branch (missing secrets fail it), unsigned elsewhere; ends in a draft release. Packaging lint and a fixture WiX build guard PRs; `src/packaging_tests.rs` keeps ids and types in step. **Opening documents on macOS** (ADR 0062): a double-click in Finder, a drop on the Dock icon or Open With opens the document, at launch or while running (the open-documents Apple Event through `platform.rs`, by `fmv-macos-events`, so no `unsafe` of ours), through the unsaved-changes guard; the Dock's Quit asks to save too; Windows and Linux command-line hand-over covered by a test. **Portable mode and AppImage desktop integration** (ADR 0094): an `anicraft-portable` marker (shipped in the Windows zip and the Linux tar.gz; also honoured beside `AniCraft.app` and an `.AppImage`) keeps preferences, autosave, logs, plug-ins, templates, recent files, brushes, filter presets and workspaces in `data/` beside the app, through one switch in `platform.rs`, falling back visibly when that folder can't be written; Preferences › About shows the mode and every folder; on first start from an AppImage a non-modal card offers once to add AniCraft to the applications menu (`desktop.integrate/remove/status`: desktop entry with a quoted `Exec`, MIME types and icons under `$XDG_DATA_HOME` only, idempotent, removable from About, following a moved or updated AppImage); a store-readiness job checks the Flatpak manifests, AppStream (`appstreamcli validate`), the desktop entry and any winget/MSIX manifests. Not yet: verified on a Mac (the checklist is in ADR 0062), a single running AniCraft taking a second document on Windows and Linux, store submissions and winget/MSIX manifests, self-update inside a portable copy, video export inside the Flatpak. |
| Documentation | **User guide, first slice** (ADR 0069, `docs/guide/`): eighteen chapters for artists (getting started to troubleshooting, and Coming from Animate), a command reference and a shortcut reference (Windows/Linux and macOS) generated from the registry and checked for freshness by tests, every link, anchor and picture checked, eight screenshots from `scripts/guide-shots.sh`. Help › User Guide opens the book bundled in the app, offline, in the browser; the web build serves it beside the editor; `anicraft-cli guide --out <folder>` writes it. Not yet: translated guides, search, a PDF edition, context help from panels, macOS and Linux screenshots. |
| Languages | **First slice** (ADR 0040, `docs/localisation.md`): every shell string goes through `tr!`/`trn!` (keyed by its English; placeholders; CLDR plurals for whole numbers), menus translate the registry's labels when drawn (ids, CLI, MCP and the file format stay English), screen-reader names too. Catalogs are craft-i18n's TSV, read by our own parser and embedded from `CRAFT_I18N_DIR` (fallback app → shared → base language → English). Preferences › Appearance › Language (system language by default) and `--lang`. A **pseudo-locale** (`--lang pseudo`: accented, a third longer, bracketed) tests layout; checked by a source guideline test and a pseudo-locale accessibility audit; `scripts/i18n-extract.sh` writes the translators' template and per-locale coverage. Not yet: a real language (craft-i18n has no `anicraft.tsv` yet), engine messages and confirmation bodies (`@msg`), default document names, right to left (needs bidi and shaping in egui upstream), CJK and Georgian (need a font), shaped scripts. |
| Accessibility | **First pass** (ADR 0022, `docs/accessibility.md`): AccessKit (via eframe) gives every control a name and role, checked by a headless test that walks the tree in 23 interface states (custom-painted tools, layer rows and toggles, icon buttons, Library rows, every Properties field, the Motion Editor, every dialog; the stage is a named canvas; the status bar a polite live region). **Ctrl+F6 / Ctrl+Shift+F6** move focus between Stage, Timeline, Properties, Library and Tools (rebindable); focused controls keep Enter/Space/arrows while other shortcuts still work; pointer-only surfaces are not Tab stops. **High contrast** palette (Preferences › Theme) from the same roles, text ≥ 7:1, controls and focus ≥ 3:1; both palettes checked by the contrast test (the graphite one now meets AA everywhere). **Interface scale** 75–200 % holds up (stage refits, tools and timeline header scroll, status truncates). **Second pass** (ADR 0064): while the stage has focus its elements are a list box under the canvas (name from the instance name and outline or kind, layer, place and size, bounds, selected; 2,000 at most plus a summary); **Tab, arrows, Enter/Space and Shift+Space select on the stage** through `element.select` (new `toggle`); the active layer's keyframe spans are a list (frames, tween, label, sound, actions; activating one moves the playhead); on the focused timeline the arrows move the playhead and layer, announced through the status bar; **the menu bar from the keyboard** on Windows and Linux (Alt tap or F10, arrows, submenus, Esc, Alt+letter with underlined access keys); **Follow system** (the default theme) switches to high contrast with Windows' contrast themes, macOS' Increase Contrast, the portal/GNOME contrast setting and `prefers-contrast` in browsers. **Light theme** (ADR 0077, #227): a third palette designed for light (paper greys, near-black text, hairline controls, timeline blocks re-tuned to 3:1 on the panels with 4.5:1 marks), checked by the same contrast test; Follow system now follows the system's light or dark mode too (Windows, macOS, portal/GNOME, `prefers-color-scheme`). Not yet: names beyond the outline heuristic, per-item menu letters, a light high-contrast palette, a keyboard route to the menu row on macOS (⌘K covers it), manual passes with Narrator, VoiceOver and Orca. |
@@ -41,7 +41,7 @@ milestone ends with a green tree: build, tests, clippy, a `--screenshot` check a
| **M5** | Rich media | ~~Text engine~~ ✅ first slice (ADR 0012: `harfrust` shaping, `skrifa` outlines, line wrapping, outlines stored with the text; per-character styles later); ~~text on a path~~ ✅ first slice (ADR 0070: a copy of a shape's outline in the block, glyphs set by arc length and stored as outlines, offset, flip and alignment, Attach to Path by picking a shape, SVG `textPath`; editing the path in place and several lines on a path later); ~~dynamic and input text fields~~ ✅ first slice (ADR 0066: Text type in Properties, instance names, `field.text`/`appendText`/`length` in scripts, typing with caret, selection, max chars and passwords in Test Movie, native inputs in the HTML export, XFL fields kept; `htmlText`, change events, embedded fonts in HTML and other `TextField` API later); ~~bitmap import and bitmap fills~~ ✅; ~~audio layers, waveform display, stream sync~~ ✅ first slice (ADR 0020: WAV, Ogg Vorbis, MP3; `cpal` output); ~~effect envelopes, layer volume and mute, sounds inside symbols~~ ✅ (ADR 0039); ~~button sounds and hit-area editing~~ ✅ (ADR 0057: state sounds in Test Movie and HTML, state names on the timeline, the Hit area over the other states, Show hit areas in Test Movie, XFL sounds in the package); ~~filters (blur, drop shadow, glow, colour matrix)~~ ✅, ~~bevel, gradient glow and gradient bevel~~ ✅ (ADR 0025; SVG export and XFL import), ~~filter presets, reordering, on/off and tweened filter values~~ ✅ (ADR 0091: drag or Alt+arrows to reorder, an eye per filter that keeps its settings, Copy/Paste Filters, presets in your preferences with a JSON file to move them; classic tweens pair lists with switched-off filters), ~~motion-tween tracks per filter property in the Motion Editor~~ ✅ (ADR 0092: blur, strength, angle, distance and Adjust Color's four, by filter slot, with curves, eases and retiming, auto-keyed from Properties › Filters, following reorders and removals; not yet: filter colours, quality and switches as tracks, Animate's filter tracks from XFL; filters on text fields and built-in presets later) and ~~blend modes~~ ✅ on Movie Clips. |
| **M6** | Interactivity & extensibility | **Plug-ins: the Craft-family WebAssembly system** (same host model as PhotoCraft: `wasmi` sandbox, `plugin.*` commands; AniCraft ABI for vector/timeline operations and exporters): first slice ✅ (command plug-ins over the registry, ADR 0017); ~~exporter and easing plug-ins~~ ✅ (ADR 0088); ~~frame scripts on the same sandbox~~ ✅ and ~~button states in test-movie preview~~ ✅ first slice (ADR 0024: action IR, pure player, Actions panel, Test Movie); ~~HTML canvas runtime export~~ ✅ first slice (ADR 0028: one self-contained page, baked frames, a JS port of the player tested against it; ~~filters, Subtract and Invert in the page~~ ✅, ADR 0072); command macros. **ActionScript compatibility, low priority** (ADR 0013), last in M6 and free to slip past M8: ~~tier 1 keeps scripts~~ ✅ (XFL frame scripts and class names stored verbatim, the Actions panel's Script view, `script.*` commands); ~~tier 2 runs the ActionScript 3 timeline subset (stop, play, go to frame or label, named instances, button events) in Test Movie and HTML canvas export through the same action IR as WebAssembly frame scripts~~ ✅; ~~tier 2.5 small logic (typed variables, expressions, `if` and loops, property reads, functions across frames, enter-frame and keyboard listeners, seeded random, ADR 0052)~~ ✅. The full language, the `flash.*` API and SWF bytecode are not planned. |
| **M7** | Advanced animation | ~~Bone/IK tool~~ ✅ first slice (ADR 0043: symbol-instance armatures on an armature layer, Bone tool, joint-angle poses tweened with easing, CCD inverse kinematics with joint limits and pins, posing with the Selection tool, Bone properties, every export; not yet: outline-following ARAP meshes, symbols, pins bound to bones, a GPU textured path, bent bitmaps in HTML/Lottie); ~~springs, joint translation, editing members in place~~ ✅ second slice (ADR 0084); not yet: runtime armatures, XFL armature import); ~~shape armatures~~ ✅ first slice (ADR 0071: bones inside one shape, automatic binding, linear blend skinning, Bind tool); ~~painted weights and reshaping a bound shape~~ ✅ second slice (ADR 0090; not yet: instances and shapes in one armature, reshaping at a posed frame); ~~asset warp~~ ✅ first slice (ADR 0079: warp meshes on shapes and bitmaps, pins, rigid MLS, pin poses tweened, Asset Warp tool, ~~camera layer with depth~~ ✅ first slice (ADR 0027: one camera layer per scene, pan/zoom/rotate/tint, classic and motion tweens, pan-only layer depth, Camera tool, Preview Through Camera, every export); ~~layer depth in perspective, keyed over time, Layer Depth panel, attaching layers, camera colour effects, editing while previewing~~ ✅ second slice (ADR 0082; not yet: tools other than Selection while previewing, depth inside symbols, XFL camera import); ~~variable-width strokes~~ ✅ first slice (ADR 0018: width profiles, Width tool, exports, tweens); ~~Brush tool~~ ✅ first slice (ADR 0033: filled sweeps, tips, pressure, Paint Normal/Fills/Behind; not yet: Paint Selection/Inside); ~~brush library, pressure curves and the Paint Brush~~ ✅ first slice (ADR 0068: parameter presets, user brushes and brush sets, curve editor, velocity, stroke mode); ~~Eraser and Eyedropper~~ ✅ first slice (ADR 0034: five erase modes, Faucet, Erase Everything; picks solid, gradient, bitmap and line styles) and brush library; ~~tilt, textured brushes, erasing inside symbols, gradients and width profiles in the merge~~ ✅ second slice (ADR 0093: tilt turns and widens the tip per sample, paper-grain texture and scatter as vector paint, Charcoal and Spatter, the Eraser's hint for symbols and objects, width profiles carried into each merged piece; not yet: reading tilt on desktop systems (winit 0.30 reports it only on iOS), bitmap, art and pattern brushes, eraser pressure and presets, the live preview through texture and tilt); ~~graph-based easing presets library~~ ✅ first slice (ADR 0081: presets, custom multi-segment eases, saved eases, per-group classic eases, Motion Editor properties, XFL import; not yet: updating every tween that uses a saved ease, a user ease library shared between documents, Lottie-native eases instead of baked frames, motion-tween eases from XFL). |
| **M8** | Release quality | ~~Installers and signing for Windows/macOS/Linux~~ ✅ first slice (ADR 0026: family `packaging/` layout, MSI, DMG, AppImage/deb/rpm/Flatpak/tar.gz, `.anicraft` registered everywhere, signing wired to the release environment; ~~opening documents from Finder~~ ✅ (ADR 0062, to be checked on a Mac); next: AppImage desktop integration, portable mode, store submissions); ~~web build (wasm) of the editor~~ ✅ first slice (ADR 0036: browser file picker and downloads, autosave in browser storage, CPU stage, CI wasm build and tests in Node, the release zip made by `packaging/web/package.sh` and checked in CI (#210); next: releases carrying it and a hosted copy, once the team decides where, Web Audio, WebGPU stage, verified in browsers); ~~localisation~~ ✅ first slice (ADR 0040: `tr!` everywhere in the shell, craft-i18n catalogs, Preferences language, pseudo-locale; next: AniCraft's catalog in craft-i18n, engine messages, right to left once egui can lay it out); accessibility: first pass ✅ (ADR 0022: screen-reader names for every control, Ctrl+F6 panel focus, high-contrast theme, 200 % scale), second pass ✅ (ADR 0064: stage elements and timeline frames for screen readers, keyboard selection on the stage, keyboard menu bar, following the system's contrast setting), ~~a light theme~~ ✅ (ADR 0077: Light palette, Follow system for light or dark, #227), next: live screen-reader passes on each platform, a light high-contrast palette; ~~crash-recovery autosave~~ ✅ (ADR 0015); ~~Find and Replace and the Movie Explorer~~ ✅ first slice (ADR 0058: `find.search`/`find.replace`/`find.goto` over text, fonts, colours, symbols, sounds and bitmaps, scene or document, linear-time patterns, Replace All as one undo step asking above 100 places, going there opens symbols in place; `explorer.tree` paged, Show filters and search, the Movie Explorer tab beside the Library, lists drawing only the rows in view; not yet: action parameters and ActionScript strings apart from code, font size and style, colour tolerance, renaming in the Movie Explorer); ~~files from the desktop, recent files and a start screen~~ ✅ first slice (ADR 0059: drops route by type and target in one undo step, Open Recent with pins and missing files, start screen with presets and thumbnails); ~~templates, SVG into the Library, drops on the timeline~~ ✅ first slice (ADR 0065: six built-in templates built in code, Save as Template with category and picture, SVG as a graphic symbol, sounds onto a frame's keyframe and media into a keyframe made there; next: exact desktop drop positions once eframe moves to winit 0.31, user template descriptions and renaming); ~~Publish Settings and Publish~~ ✅ first slice (ADR 0060: the publish profile in the document, every format with its export options and an output relative to the document's folder with `{name}`, Shift+F12 publishing in the background with progress, Cancel and one report, overwriting asked once per session, presets in Preferences, the browser's downloads as one ZIP; not yet: Animate's PublishSettings.xml from XFL, more placeholders, outputs outside the document's folder, progress inside HTML, Lottie and audio); ~~documentation book~~ ✅ first slice (ADR 0069: the user guide in `docs/guide/`, generated command and shortcut references, Help › User Guide offline; next: translated guides, search, PDF, context help); ~~dockable panels and workspaces~~ ✅ first slice (ADR 0075, #249: every panel docks on any side of the stage, stacks as tabs, resizes, folds, floats in a window of its own with ADR 0062's fallback, closes and reopens where it was from the Window menu; Essentials, Animator, Designer and your own workspaces with Reset, kept in the preferences; new Colour and Output panels; Ctrl+F6 follows the layout), second slice ✅ (ADR 0087: the tools move like any panel, as a slim bar on any side or a tab laid out in columns; floating windows hold several tabs and drag back into a dock by their grip or title bar with the drop targets shown; docks collapse to strips of panel icons with flyouts over the stage (Esc or a click outside closes them); Manage Workspaces renames and deletes your own (built-in ones reset only); every panel fits the narrowest dock (200 pt), form rows wrapping under their label, checked by test in English and the pseudo-locale; not yet: dragging between two windows of their own on mixed-DPI screens verified by hand, panels side by side inside a floating window, columns of groups in one dock, minimum sizes per panel, panel shortcut keys). |
| **M8** | Release quality | ~~Installers and signing for Windows/macOS/Linux~~ ✅ first slice (ADR 0026: family `packaging/` layout, MSI, DMG, AppImage/deb/rpm/Flatpak/tar.gz, `.anicraft` registered everywhere, signing wired to the release environment; ~~opening documents from Finder~~ ✅ (ADR 0062, to be checked on a Mac); ~~AppImage desktop integration, portable mode, store readiness checks~~ ✅ (ADR 0094); next: store submissions); ~~web build (wasm) of the editor~~ ✅ first slice (ADR 0036: browser file picker and downloads, autosave in browser storage, CPU stage, CI wasm build and tests in Node, the release zip made by `packaging/web/package.sh` and checked in CI (#210); next: releases carrying it and a hosted copy, once the team decides where, Web Audio, WebGPU stage, verified in browsers); ~~localisation~~ ✅ first slice (ADR 0040: `tr!` everywhere in the shell, craft-i18n catalogs, Preferences language, pseudo-locale; next: AniCraft's catalog in craft-i18n, engine messages, right to left once egui can lay it out); accessibility: first pass ✅ (ADR 0022: screen-reader names for every control, Ctrl+F6 panel focus, high-contrast theme, 200 % scale), second pass ✅ (ADR 0064: stage elements and timeline frames for screen readers, keyboard selection on the stage, keyboard menu bar, following the system's contrast setting), ~~a light theme~~ ✅ (ADR 0077: Light palette, Follow system for light or dark, #227), next: live screen-reader passes on each platform, a light high-contrast palette; ~~crash-recovery autosave~~ ✅ (ADR 0015); ~~Find and Replace and the Movie Explorer~~ ✅ first slice (ADR 0058: `find.search`/`find.replace`/`find.goto` over text, fonts, colours, symbols, sounds and bitmaps, scene or document, linear-time patterns, Replace All as one undo step asking above 100 places, going there opens symbols in place; `explorer.tree` paged, Show filters and search, the Movie Explorer tab beside the Library, lists drawing only the rows in view; not yet: action parameters and ActionScript strings apart from code, font size and style, colour tolerance, renaming in the Movie Explorer); ~~files from the desktop, recent files and a start screen~~ ✅ first slice (ADR 0059: drops route by type and target in one undo step, Open Recent with pins and missing files, start screen with presets and thumbnails); ~~templates, SVG into the Library, drops on the timeline~~ ✅ first slice (ADR 0065: six built-in templates built in code, Save as Template with category and picture, SVG as a graphic symbol, sounds onto a frame's keyframe and media into a keyframe made there; next: exact desktop drop positions once eframe moves to winit 0.31, user template descriptions and renaming); ~~Publish Settings and Publish~~ ✅ first slice (ADR 0060: the publish profile in the document, every format with its export options and an output relative to the document's folder with `{name}`, Shift+F12 publishing in the background with progress, Cancel and one report, overwriting asked once per session, presets in Preferences, the browser's downloads as one ZIP; not yet: Animate's PublishSettings.xml from XFL, more placeholders, outputs outside the document's folder, progress inside HTML, Lottie and audio); ~~documentation book~~ ✅ first slice (ADR 0069: the user guide in `docs/guide/`, generated command and shortcut references, Help › User Guide offline; next: translated guides, search, PDF, context help); ~~dockable panels and workspaces~~ ✅ first slice (ADR 0075, #249: every panel docks on any side of the stage, stacks as tabs, resizes, folds, floats in a window of its own with ADR 0062's fallback, closes and reopens where it was from the Window menu; Essentials, Animator, Designer and your own workspaces with Reset, kept in the preferences; new Colour and Output panels; Ctrl+F6 follows the layout), second slice ✅ (ADR 0087: the tools move like any panel, as a slim bar on any side or a tab laid out in columns; floating windows hold several tabs and drag back into a dock by their grip or title bar with the drop targets shown; docks collapse to strips of panel icons with flyouts over the stage (Esc or a click outside closes them); Manage Workspaces renames and deletes your own (built-in ones reset only); every panel fits the narrowest dock (200 pt), form rows wrapping under their label, checked by test in English and the pseudo-locale; not yet: dragging between two windows of their own on mixed-DPI screens verified by hand, panels side by side inside a floating window, columns of groups in one dock, minimum sizes per panel, panel shortcut keys). |
## Releases
@@ -62,7 +62,7 @@ titled with its milestone.
| M5 | Audio layers: import, waveform, playback sync | timeline, layers |
| M6 | ~~WebAssembly plug-ins (U2)~~ ✅ first slice (ADR 0017); ~~frame scripts and Test Movie on the plug-in host~~ ✅ first slice (ADR 0024); ~~HTML canvas runtime export~~ ✅ first slice (ADR 0028); ~~ActionScript tier 1: keep scripts~~ ✅ (ADR 0013); ~~ActionScript tier 2: run the timeline subset~~ ✅ (ADR 0013); ~~ActionScript tier 2.5: small logic~~ ✅ (ADR 0052); ~~exporter and easing plug-ins~~ ✅ (ADR 0088); next: command macros, or growing the ActionScript subset (`switch`, arrays, event bubbling) | command registry, plug-in host, action IR and player |
| M7 | ~~Variable-width strokes~~ ✅ (ADR 0018), ~~camera layer with depth~~ ✅ first slice (ADR 0027), ~~camera depth, attaching and colour~~ ✅ (ADR 0082), ~~Bone tool and IK~~ ✅ first slice (ADR 0043), ~~shape armatures and the Bind tool~~ ✅ first slice (ADR 0071), ~~painted weights and reshaping~~ ✅ (ADR 0090), ~~bone springs and joint translation~~ ✅ (ADR 0084), ~~Asset Warp~~ ✅ first slice (ADR 0079), ~~Brush tool~~ ✅ first slice (ADR 0033), ~~Eraser and Eyedropper~~ ✅ first slice (ADR 0034); ~~brush library and pressure curves~~ ✅ first slice (ADR 0068), ~~tilt, texture, profiles in the merge~~ ✅ (ADR 0093); next: reading pen tilt from the toolkit, art brushes | strokes, Pen and Pencil, width profiles, timeline evaluation |
| M8 | ~~Crash-recovery autosave~~ ✅, ~~accessibility first pass~~ ✅ (ADR 0022), ~~installers and signing~~ ✅ first slice (ADR 0026), ~~web build~~ ✅ first slice (ADR 0036), ~~localisation~~ ✅ first slice (ADR 0040), ~~Find and Replace and the Movie Explorer~~ ✅ first slice (ADR 0058), ~~drops, recent files and the start screen~~ ✅ first slice (ADR 0059); ~~templates and drops on the timeline~~ ✅ first slice (ADR 0065); ~~Publish Settings and Publish~~ ✅ first slice (ADR 0060); ~~Test Movie in its own window and macOS document opening~~ ✅ first slice (ADR 0062); ~~accessibility second pass~~ ✅ (ADR 0064); ~~a light theme~~ ✅ (ADR 0077); ~~CI on macOS and Windows~~ ✅ (ADR 0067); ~~dockable panels and workspaces~~ ✅ first and second slices (ADR 0075, ADR 0087); next: live screen-reader passes | `.anicraft` format, session, AccessKit in eframe |
| M8 | ~~Crash-recovery autosave~~ ✅, ~~accessibility first pass~~ ✅ (ADR 0022), ~~installers and signing~~ ✅ first slice (ADR 0026), ~~portable mode and AppImage desktop integration~~ ✅ (ADR 0094), ~~web build~~ ✅ first slice (ADR 0036), ~~localisation~~ ✅ first slice (ADR 0040), ~~Find and Replace and the Movie Explorer~~ ✅ first slice (ADR 0058), ~~drops, recent files and the start screen~~ ✅ first slice (ADR 0059); ~~templates and drops on the timeline~~ ✅ first slice (ADR 0065); ~~Publish Settings and Publish~~ ✅ first slice (ADR 0060); ~~Test Movie in its own window and macOS document opening~~ ✅ first slice (ADR 0062); ~~accessibility second pass~~ ✅ (ADR 0064); ~~a light theme~~ ✅ (ADR 0077); ~~CI on macOS and Windows~~ ✅ (ADR 0067); ~~dockable panels and workspaces~~ ✅ first and second slices (ADR 0075, ADR 0087); next: live screen-reader passes | `.anicraft` format, session, AccessKit in eframe |
Tasks that wait on an open track: XFL motion tweens (on M2's motion tweens); frame scripts and
ActionScript (on M6's plug-in host).
+43
View File
@@ -0,0 +1,43 @@
# Packaging
How AniCraft is built into installers (ADR 0026). The family's shared release workflow
(`storytold/craft-common-actions`) runs these scripts; `docs/release.md` describes a release.
| Path | What |
|---|---|
| `env.sh` | Version, build variables and `APP_ID`, sourced by every script |
| `check-icons.sh` | The icons every package names exist |
| `check-store-readiness.sh` | Store metadata checks: Flatpak manifests, AppStream, desktop entry, winget/MSIX (ADR 0094) |
| `windows/` | MSI (WiX v5), portable zip, symbols zip; install policy checks ([README](windows/README.md)) |
| `macos/` | Universal `AniCraft.app` on a DMG, CLI zip, signing and notarization |
| `linux/` | AppImage, deb, rpm, tar.gz; Flatpak manifests; desktop entry, metainfo, MIME types |
| `web/` | The web build's zip |
## Portable copies (ADR 0094)
The Windows zip and the Linux tar.gz contain a file named `anicraft-portable` at their top. A
copy with that marker keeps preferences, autosave, logs, plug-ins, templates, thumbnails and the
offline guide in a `data/` folder beside the marker instead of the user's settings folder. The
app looks for the marker next to the program, above `bin/`, next to `AniCraft.app` (macOS) and
next to the `.AppImage`. Installed packages (MSI, DMG, deb, rpm, Flatpak, Arch) never ship it.
Preferences › About shows which kind of copy is running and its folders.
## AppImage desktop integration (ADR 0094)
The AppImage's `AppRun` starts the app directly. On the first start, the app offers once
(non-modally) to add itself to the applications menu; the engine's `desktop.integrate` then writes
the desktop entry (with `Exec` pointing at the `.AppImage`), the MIME types and the hicolor icons
from this folder into `$XDG_DATA_HOME` (`~/.local/share`), never into system folders.
Preferences › About removes them (`desktop.remove`). Headless:
```sh
anicraft-cli exec --sample desktop.integrate '{"appimage": "/home/me/Apps/AniCraft.AppImage", "data_home": "/home/me/.local/share"}'
```
## Store readiness
`check-store-readiness.sh` runs in the Packaging lint workflow (`store-readiness` job) and
locally (it skips tools that aren't installed). It validates; it never submits. Submissions to
Flathub, winget and the Microsoft Store are made by the team. winget manifests go in
`windows/winget/*.yaml` and an MSIX manifest in `windows/msix/AppxManifest.xml`; the check reads
their required fields once they exist.