Session state (contributors)

Phials persists per-session UI data under ~/.phials/state/ (or PHIALS_HOME), typically as JSON via StateManager (src/core/state/state-manager.svelte.ts). This is separate from portable preferences in config.toml.

favoritesItems

Navigator favorites live on SessionRecord.favoritesItems as a flat array of FavoriteItem records (see src/core/settings/settings-manager.types.d.ts).

Field	Role
kind	"location" (default if omitted) or "group"
parentId	null for top level; group id for locations inside a folder
order	Sort index within the same parentId scope
path	Folder path for locations; null for groups and system rows
collapsed	Optional; group expand/collapse

FavoritesManager normalizes data on load and persist (normalizeFavoritesItems in src/core/managers/favorites/favorites.logic.ts):

• Missing kind → location; missing parentId → top level
• Invalid parent references are repaired (orphan locations promoted; groups cannot be nested)
• order is compacted per scope

Legacy flat session files without kind / parentId migrate to top-level locations without data loss.

Plugins

FavoriteItem and favoritesItems are not part of the public plugin API (ReadonlyAppSettings does not expose favorites). Do not add them to the SDK without a contract version bump and documented migration.

Built-in pin/unpin behavior uses FavoritesManager helpers (addItem, removeByPath, updatePath) via src/plugins/builtin/commands/file-commands.ts.