Skip to content
sysout.dev

treeger - Spaces Feature Brief

Product and architecture decisions for Explorer, Gallery, Documents, and future configurable Treeger Spaces.

Purpose And Status

This document is the canonical product, architecture, and delivery reference for Spaces. It expands the direction in the roadmap’s Spaces section into a clear model, the implemented JSON and runtime boundaries, and a sequence of independently testable deliverables.

Spaces is currently a debug-only product lab. The first prototype proved that the existing Home and a cross-folder Gallery could be exposed through a selector, but it also exposed a product-model problem: Home, hierarchical folder browsing, and the Gallery feed were separate screen implementations rather than clear instances of a Space definition.

The current decision corrects that model before shared Gallery actions or custom Spaces make the screen-first structure more expensive to change. Home is the application dashboard and is not a Space. The two built-in Spaces are Explorer and Gallery. They share file identities, capabilities, and operation semantics, while differing through explicit source, membership, browsing, and presentation configuration. The existing prototype remains useful evidence, but its Files label and Home-based selector are not the intended final navigation.

A debug-only Documents definition is also present as an architectural proof. It does not expand the decided release scope: its purpose is to verify that a third Space can be added through configuration without another screen, route, session, or Space-ID branch.

How The Direction Evolved

Original Roadmap Hypothesis

The original roadmap treated a Space as a named Home configuration. Its primary problem was Home clutter: work, personal, travel, photography, and project modules could accumulate in one layout. A user might create separate configurations with different pins, modules, ordering, and view preferences.

That proposal deliberately required evidence before delivery:

  • Edit Home should exist first.

  • Enough independent modules should exist to make configurations meaningfully different.

  • Users should demonstrate a recurring need for two or more configurations.

  • If one tidy Home solved the problem, Spaces should not add another concept.

Persona-Oriented Out-Of-The-Box Proposal

The next proposal broadened Spaces from requested configurations to useful out-of-the-box views. Possible research archetypes included:

  • document-heavy users such as executives;

  • media-heavy users such as creators and social-media users; and

  • general users with a mixture of documents and media.

The important observation was not the persona label itself. It was that useful content crosses folder boundaries. Images and videos may be spread across Camera, Screenshots, Downloads, WhatsApp, Signal, Telegram, editing applications, and other locations. A folder pin alone cannot present that collection.

Discovery Approach Initially Considered

The proposed discovery approach treated personas as hypotheses rather than durable user identities. It suggested learning interests through an evidence hierarchy:

  1. explicit user choices, such as selecting Documents or Photos and media;

  2. meaningful actions, such as opened files, pins, and repeated searches;

  3. local file-type, recency, and folder distribution; and

  4. weak source heuristics based on folder paths or application attribution.

It also proposed interviews, prototype comparison, representative synthetic device libraries, and longitudinal testing. Evidence would have been required to show that people wanted multiple recurring configurations and that inferred suggestions were relevant, understandable, and privacy-respecting.

No user interviews were conducted as part of this discussion. This was a proposed discovery plan, not collected evidence.

Why The Original Evidence Gate Was Withdrawn

treeger is not an established file manager looking for an optional customisation feature. Its intended niche is to replace two applications commonly present on a phone: a file manager and a local gallery.

That background changes the question. Sometimes a user needs a location-first filesystem view; at other times the same user needs a visual, content-first media view. Switching between those modes is part of the intended product, not a behavior that persona inference or interviews must first prove.

The requirement to prove demand for two recurring configurations is therefore withdrawn for the two built-in Spaces. Interviews remain useful for refining the minimum gallery experience, source expectations, and future custom Spaces, but they are not a prerequisite for implementing Explorer and Gallery.

Evidence has shifted from whether Spaces should exist to whether the execution is credible enough to release.

What The Screen-First Prototype Exposed

The initial implementation called Home Files and treated Gallery as another screen selected from it. That was sufficient to test cross-folder media discovery, but it did not answer how another built-in or custom Space would be defined. In particular, neither implementation declared:

  • which folders contribute content;

  • whether users navigate the folder hierarchy or see content aggregated from it;

  • which file types are permanent members rather than temporarily filtered results;

  • which layout, sorting, and grouping rules are defaults; or

  • how shared actions and file opening remain identical across entry points.

This was not only a naming issue. Extracting either screen directly would preserve incidental UI structure instead of exposing the dimensions that actually vary.

Alternatives Considered And Withdrawn

Several broader abstractions were considered while trying to reconcile Files, Gallery, Documents, and future custom Spaces:

  • Treat a Space as a navigation domain that might contain an optional Overview, hierarchy, collection, and configurable landing destination.

  • Distinguish simple collection Spaces from composed dashboard templates.

  • Treat Files and Gallery as application modes, Documents as a view, and reserve custom dashboards as a separate future workspace concept.

These models identified useful distinctions but introduced concepts to accommodate the current screens rather than producing a definition that was easy to explain. In particular, mandatory or optional per-Space Overviews duplicated the role of Home, and simple-versus-composed templates created a second Space taxonomy before custom Spaces had been designed.

The adopted model instead separates the application dashboard from Spaces and defines a Space by file scope and browsing behavior. It does not require every Space to have the same screen structure, nor does it turn current implementation differences into permanent Space types.

Decided Product Thesis

treeger has one application Home and multiple persistent Spaces over the same underlying files:

  • Home is the application-wide dashboard. It owns the Spaces entry section, Recently Used, Pins, and Storage regardless of where an item was opened.

  • Explorer answers "Where is this file?" by showing direct folder contents and allowing hierarchical navigation.

  • Gallery answers "Show me my media" through a visual collection that crosses folder boundaries and is organised for browsing.

Explorer and Gallery are built in and available without persona detection or an interest-onboarding flow. Persona- or interest-informed Spaces may be explored later, after the two built-in Spaces establish a stable model.

Product Model

Concept Meaning

Home

The application-wide dashboard outside every Space. It presents entry points to Spaces and shared activity or navigation data such as Recently Used, Pins, and Storage.

Space

A named, persistent definition of which existing files can be browsed and how they are initially presented. A Space is not a storage container and does not own or copy its results.

Explorer Space

The built-in hierarchical Space over readable storage. It shows the direct folders and files at the current location and uses normal folder navigation.

Gallery Space

The built-in content Space over readable storage. Images and videos are permanent members and are aggregated recursively into a visual timeline.

Included folder

A source root whose descendants may be presented by a Space. Including a folder does not move it or give the Space ownership of it.

Browse type

Hierarchical shows direct folders and files and supports folder drill-down. Content recursively projects matching files from included folders without using the source hierarchy as the primary presentation.

Content membership

The permanent file-type scope of a Space: all content or specified content types. Clearing temporary filters never expands results beyond this membership.

Layout

The visual arrangement of current results, initially List or Grid. Browse type and layout are separate: a Content Space may default to Grid and later switch to List.

Filter

A temporary narrowing of a Space’s current results, such as media type or parent location. A filter does not move files or create another navigation destination.

Collection

A possible named, persistent subset within a future Space. Collections are not required for the initial Gallery filtering model.

Source

The explainable location from which a result came. Folder and path evidence is preferred over an opaque claim about the application that created a file.

Space Definition Axes

The conceptual definition is intentionally small:

SpaceDefinition
  id
  name
  icon
  included folders
  browse type: Hierarchical | Content
  content membership: All | specified types
  default layout: List | Grid | future shared layouts

Search, temporary filters, sort, grouping, selection, and file actions are shared capabilities applied to the definition and current results. They are not separate Gallery implementations or configurable action policies owned by a Space.

Axis Explorer Gallery

Included folders

Readable storage roots

Readable storage roots

Browse type

Hierarchical

Content

Content membership

All

Images and videos

Default layout

List or remembered per-folder layout

Grid

Default grouping

Shared folder grouping and active sort

Effective media date, newest first

Opening context

Current folder ordering

Current filtered Gallery ordering

Gallery initially uses temporary filters rather than top-level collections so its mixed-media chronology remains intact. A future Collection would still be intentionally narrower than a user-defined Smart Stack and would remain a projection over the shared search and file model rather than requiring a permanent content index.

Browse Engine And Session Boundary

SpaceDefinition is executable input to one of two browse engines rather than metadata interpreted independently by each screen:

  • the hierarchical engine exposes the definition’s included folders as roots and lists direct children when the session is at a concrete folder;

  • the content engine recursively searches every included folder, applies permanent content membership, merges progress, and de-duplicates overlapping results by file URI; and

  • the screen host applies temporary filters, grouping, layout, selection, and actions to the engine results.

The distinction is deliberately an engine boundary, not a when (space) spread through UI code. Explorer currently enters its single built-in root directly, but the hierarchical root contract already represents multiple included folders for a future custom Space. Gallery continues to use the existing incremental search implementation through the content engine; this does not introduce a media index.

Runtime navigation state is keyed by Space identity. A hierarchical Space retains its current folder and breadcrumbs when the user switches away, while Gallery retains its existing filters and scroll session. Changing a future Space definition with the same identity still causes its content input to be reloaded when the definition itself has changed.

Shared Presentation Boundary

List and Grid are represented by the same SpaceLayout model in every Space. There is no longer a separate Explorer-only folder view-mode type. Both built-in Spaces use the same layout control and begin from the definition’s default layout:

  • Explorer may apply its existing media-folder default and remembers explicit per-folder overrides using the existing persisted List and Grid values;

  • Gallery defaults to Grid, offers a List presentation over the same filtered and grouped results, and retains its layout with its in-memory Gallery session; and

  • switching layout changes presentation only. It does not rescan, alter permanent membership, clear filters, or create a separate result set.

The row and tile renderers remain browse-template appropriate. Sharing a layout axis does not require Gallery rows and Explorer rows to show identical metadata; the reusable boundary is the layout model, control, result identity, scroll context, and shared file behavior.

Shared Space Host Boundary

Every Space enters the UI through one SpaceScreen. It receives three distinct kinds of input rather than treating a built-in screen as the definition of a Space:

  • SpaceDefinition supplies persistent Space identity, scope, browse type, permanent content membership, and presentation default;

  • SpaceDestination supplies transient navigation, currently either the content root or a hierarchical folder with breadcrumbs; and

  • SpaceHost supplies shared application capabilities and callbacks such as permission requests, Space switching, file opening, and back navigation.

SpaceScreen selects a hierarchical or content browser only from the definition’s browse type. It does not branch on the Explorer or Gallery identity. A destination must match that browse type, so folder navigation cannot accidentally be passed to a Content Space and a Hierarchical Space cannot silently discard its location.

The browser implementations remain responsible for browse-type-specific rendering and interaction. This does not mean they remain independent screens. The host routes both built-ins through SpaceScreen and the former screen composables are now hierarchical and content browsers. SpaceScreen owns the shared Search and Sort session and callbacks, while shared host components render the Search field, general filter row, Search action, and Sort menu in either browser’s chrome.

The browser consumes that common state according to its browse semantics. A hierarchical browser executes the query at the selected folder scope and retains its incremental progress and cancellation UI. A content browser applies the same name, type, modified-date, and size rules to its already aggregated result snapshot, then uses the shared sort and grouping rules. Typing in a Content Space therefore does not restart a recursive storage scan. Content Spaces may expose definition-valid type choices and a shared Location projection as quick filters layered before the general Search filters. The host derives the general type-filter choices from permanent content membership, so Gallery offers Any, Images, and Videos rather than impossible Documents or Folders choices. Documents receives its valid intersection from the same rule without a new screen implementation.

Browse sessions are keyed by Space identity and destination. Query, temporary filters, Search expansion, and Sort are owned by the host; content scan progress, layout override, location projection, resolved source metadata, and scroll are also retained independently per Content Space. Selection and the remaining scaffold coordination still live inside the browser implementations so this migration can be verified without rewriting all interaction state at once.

SpaceHost is deliberately not called DefaultSpaceConfig: its values are shared runtime infrastructure, not defaults that a Space may override. Shared capabilities must not become optional definition flags merely because their UI has not yet been migrated from one browser.

Definition Storage And Startup

Built-in and debug-lab Space definitions live in app/src/main/assets/spaces.json. The application reads and validates this bundled configuration once when the navigation host starts. Compose retains the resulting immutable SpaceRegistry for the application session; the asset itself is already packaged locally, so no remote fetch or second cache is required.

The versioned JSON schema contains only declarative Space axes:

{
  "schemaVersion": 1,
  "spaces": [{
    "id": "documents",
    "name": "Documents",
    "icon": "file",
    "includedFolders": [{
      "root": "internalStorage",
      "displayName": "Internal storage"
    }],
    "browseType": "content",
    "contentMembership": {
      "mode": "specific",
      "types": ["documents"]
    },
    "defaultLayout": "list"
  }]
}

Named roots keep device-specific URIs out of the asset. Startup resolves internalStorage to the current device URI before constructing definitions. Unknown schema versions, roots, enum values, empty memberships, blank identities, or duplicate IDs fail validation rather than silently dropping a Space.

Navigation is registered once for a generic Space ID and destination. Content sessions are maps keyed by SpaceId; neither navigation nor state ownership lists Explorer, Gallery, or Documents. Consequently the debug Documents proof was added by one entry in spaces.json. No DocumentsScreen, Documents route, Documents session, or Documents ID branch exists.

Decisions By Axis

Axis Decision Consequence

Home ownership

Home is outside Spaces.

Recent activity, Pins, Storage, and Space launchers do not need to be duplicated as per-Space Overview pages.

Space identity

The built-ins are Explorer and Gallery.

Files no longer ambiguously names both Home and folder browsing.

Folder scope

Each Space declares included folders.

Multiple roots and future custom scopes use one membership model; overlapping roots must not duplicate file identities.

Browsing

A Space is Hierarchical or Content.

Explorer navigates direct contents; Gallery recursively aggregates matching content.

Membership versus filtering

Content types define permanent membership; filters are temporary projections.

Clearing Gallery’s Photos filter returns all Gallery media, not every file.

Presentation

Layout is independent of browse type and has a Space default.

Content defaults to Grid but may use List later without changing membership.

Common capabilities

Search, filters, sort, grouping, selection, and file actions use shared rules.

Missing Gallery actions are delivery gaps, not intentional Space policy.

File opening

A shared resolver chooses an internal viewer when supported and Android Open with otherwise.

The same file opens consistently regardless of whether it came from Home, Explorer, Gallery, or a future custom Space.

Viewer context

The originating result ordering is retained when available.

Previous/next follows the visible folder or filtered content results instead of silently changing to another Space’s ordering.

Custom Spaces

Future custom Spaces use the same definition axes.

Their editor, persistence, and exact scope remain later delivery work, without a separate simple/composed template taxonomy.

Fixed Constraints And Interaction Decisions

Shared Infrastructure Only

Every Space must reuse and, where necessary, extend the existing shared infrastructure:

  • FileItem and normal file URIs;

  • FileSearchEngine, SearchFilters, and search progress;

  • groupFolderItems and shared sort/grouping rules;

  • FileThumbnailLoader and FileArtwork;

  • launchFile and Recent history;

  • FileSelection, properties, sharing, and the operation shelf; and

  • the existing Trash implementation for explicit filesystem deletion outside Space membership.

Spaces must not introduce parallel file identities, duplicate operation engines, gallery-owned copies, or separate delete semantics. If a required capability is missing, it should normally be added to the shared layer so Explorer and future Spaces can benefit from it.

No permanent media index is part of the initial plan. If measurements show that the shared search path cannot satisfy Gallery performance, that is a separate architecture decision and must be recorded before a new index or platform query source is introduced.

Shared File Actions

File actions are not configured per Space. Their meaning and availability are derived from the selected files, filesystem or provider capabilities, and current operation state. A photo selected in Gallery can be renamed, shared, copied, moved, opened with another application, inspected, or moved to Trash under exactly the same rules as the same photo selected in Explorer.

The earlier read-only Gallery was an incomplete prototype, not a read-only Space type or policy. Gallery selection now calls the existing shared actions and operation shelf rather than registering a Gallery action list.

The following related controls are intentionally distinguished from file actions:

  • location actions such as Create folder and Copy here require a current writable destination;

  • view commands such as Refresh, Filter, Sort, Group, and Change layout affect the current presentation;

  • navigation commands such as Show in Explorer change context; and

  • future commands such as Edit Space or Remove from Space change Space configuration or membership, not an underlying file.

Shared Opening And Viewer Context

Opening is resolved centrally from the item and available treeger capabilities:

  • folders open in a hierarchical folder view;

  • supported images and videos open in treeger’s internal viewers;

  • future supported formats, such as PDF, register another internal viewer; and

  • unsupported formats fall back to Android Open with.

The viewer itself is shared rather than owned by Gallery. When an item is opened from a Space, the originating visible ordering is retained for adjacent-item navigation. Gallery therefore pages through its active filtered results, Explorer can page through an appropriate current-folder snapshot, and a future custom Space can retain its own results. Home has no originating Space: a recent image or video enters the shared viewer directly so Back returns to Home, while a Pin or Storage destination enters a hierarchical browsing context. Every successful internal or external open updates the same application-wide Recent history.

File Safety And Removal

Space membership and file ownership remain separate:

  • Switching, hiding, or deleting a Space never changes an underlying file.

  • A future Remove from Space action changes only custom-Space configuration.

  • Gallery’s prototype initially exposed no delete action only because shared selection and actions had not yet been integrated; that omission was never a Space policy.

  • Delete from any Space invokes the existing treeger Trash flow, including its progress, undo, restore, retention, and failure behavior.

  • No Space may permanently delete an underlying file directly. Permanent deletion remains the separate, secondary action in Trash.

Application Home

Home remains the application root and gains a Spaces section containing Explorer, Gallery, and future custom Spaces. It also retains shared Recently Used, Pins, and Storage sections. Storage initially exposes Device Storage and may later add removable storage or provider-backed destinations. These modules are application-wide rather than filtered by whichever Space was last active.

Home does not display a selected-Space dropdown because no Space is active there. Selecting a Space card enters that Space. Selecting a recent item uses the shared opening resolver; selecting a Pin or Storage destination deep-links into a hierarchical browsing context at that location.

Navigation

Within a Space, the current folder or Space name remains the top-app-bar title. One overflow action directly opens a Browse options sheet whose labeled Space chips switch between concrete Space labels, initially Explorer, Gallery, and Documents. It is available at appropriate nested Space destinations and is not shown on Home. Returning Home uses normal application navigation rather than pretending Home is another Space.

Each Space retains its relevant session context while the application remains alive: current folder or result set, active filters, sort/group/layout preferences, scroll position, and viewer selection where applicable. A direct navigation request such as Show in Explorer opens the requested folder rather than the Explorer’s ordinary retained location.

A centered vertical rail on the right side with icons is a possible later visual experiment. It should be evaluated only after the functional model is useful; it is not a foundation dependency.

Debug-First Delivery

New Spaces functionality remains reachable only in debug builds until the release gate in this document is satisfied. Release builds must retain the established navigation and behavior during the lab period.

Current Prototype Baseline

The first prototype currently provides the following testable implementation. Its Home-as-Files shell and absence of Gallery file actions predate, and are superseded by, the decided model above:

  • a Files dropdown on debug Home and a Gallery dropdown on the Gallery screen;

  • a debug-only Gallery navigation destination;

  • recursive discovery of images and videos across internal storage using the existing search engine;

  • incremental scan progress, hidden-file exclusion, and treeger Trash exclusion;

  • an uncapped Gallery result collection without changing the normal Search limit;

  • capture-date extraction for local images and videos with modified-date fallback;

  • newest-first grouping using the effective media date;

  • process-retained scan results and grid position while switching Spaces;

  • explicit refresh, cancellation, and rescan behavior;

  • a dense filename-free media grid with accessibility labels and a compact extension/size overlay plus a folder-derived source icon or a system-provided application icon when available;

  • retained Gallery filters for media type and grouped, full-path location without splitting the default mixed-media timeline;

  • existing image thumbnails plus shared, memory-cached video thumbnails with fallback artwork and a play indicator;

  • an in-app media-viewer route over an origin-aware snapshot of the visible ordering;

  • horizontal and explicit previous/next navigation between media;

  • pinch zoom for images and basic platform video playback controls;

  • fit-width image viewing with vertical scrolling for media taller than the Peek viewport;

  • the same shared Properties bottom sheet used by Files;

  • external Open with through the established file handoff; and

  • Recent-history recording when each item enters Peek.

The prototype intentionally does not yet provide albums, selection, sharing, copy/move, or Gallery Trash actions. Switching is available from Files Home and Gallery, not yet from a nested folder screen. The current scan covers primary internal storage; additional removable-storage volumes remain release-hardening work.

Ordered Deliverables

Each numbered component below is intended to be one reviewable delivery. Later components may be divided further if implementation or testing reveals a useful smaller boundary.

1. Space Shell And Debug Navigation

Status: Historical prototype delivered; product model superseded.

Outcome: The prototype proved that two persistent file presentations could be switched without changing release navigation. It did not establish the final Home or Space definition.

Functionality:

  • Add the right-side top-app-bar dropdown.

  • Historically treat the existing Home as Files.

  • Register Gallery only in debug builds.

  • Switch back to the existing Files Home without creating a second Files screen.

Implementation boundary: UI and navigation state only. No storage or file model changes belonged to the prototype shell. The replacement navigation is owned by delivery 7: Home remains outside Spaces, gains a Spaces section, and the selector appears only inside loaded Spaces.

2. Cross-Folder Gallery Feed

Status: Prototype delivered.

Outcome: Gallery proves that media from multiple folders can be presented in one visual feed using the existing infrastructure.

Functionality:

  • Add a shared Images-and-videos search filter.

  • Recursively search readable internal storage.

  • Present results incrementally in a grid.

  • Reuse modified-date grouping, image artwork, file handoff, and Recent history.

  • Keep the screen read-only.

Implementation boundary: No MediaStore-specific repository, permanent index, album database, or Gallery-owned file state.

3. Scan Lifecycle And Timeline Correctness

Status: Delivered for the current debug internal-storage scope.

Outcome: The aggregate feed becomes stable enough for repeated real-device use.

Functionality:

  • Move the active Gallery snapshot into retained screen/ViewModel state so a Space switch does not immediately restart the scan.

  • Define refresh and cancellation behavior.

  • Remove traversal-order bias caused by the generic result limit, using an extension of the shared search pipeline rather than a parallel Gallery scanner.

  • Establish a shared media date with capture date when reliably available and modified date as an explicit fallback.

  • Handle unreadable folders, changed files, duplicate paths, and empty results predictably. Extend the same behavior to removable-storage volumes during release hardening.

Acceptance focus: Returning to Gallery restores useful context; newest grouping is correct for representative libraries; scanning remains cancellable and does not block browsing.

4. Media Grid And Thumbnail Quality

Status: Delivered in the debug lab.

Outcome: The feed becomes visually credible as a gallery rather than a file grid with a media filter.

Functionality:

  • Refine grid density, spacing, placeholders, and filename treatment.

  • Show a compact file-extension and size overlay where it adds useful context.

  • Extend the shared thumbnail loader to produce bounded video thumbnails.

  • Preserve fast memory-cached image loading.

  • Distinguish video clearly without overwhelming the media.

  • Keep orientation changes and large libraries memory-safe.

Acceptance focus: Scrolling remains smooth, tiles remain stable while thumbnails load, and image or video failures degrade to understandable shared artwork.

5. Peek And Media Viewing

Status: Delivered as a debug-lab first slice.

Outcome: Users can inspect media without leaving treeger or losing Gallery context.

Functionality:

  • Reuse the roadmap’s Peek concept as the internal Gallery viewer.

  • Open the selected item and move to adjacent Gallery items.

  • Support image zoom and essential video playback controls incrementally.

  • Retain Open with as a fallback and record successful Peek entry in Recent.

  • Open the existing shared Properties sheet from an Info action.

  • Defer Delete until the shared Trash action is integrated; never add a viewer-specific permanent-delete path.

Implementation boundary: Peek remains a shared file-preview capability. It must not become a Gallery-only copy of file opening, properties, or sharing.

The first slice reuses bounded bitmaps from the shared thumbnail loader for image display and Android’s platform video view for essential playback. Format support, zoom/pan constraints, lifecycle polish, and richer playback may be refined through real-device testing without changing the shared Peek contract.

Initial device testing measured the first Gallery scan at approximately 5-10 seconds. This is the current baseline rather than a release target. The retained snapshot prevents the same scan from being repeated on every Space switch; later performance work should measure library size and device class alongside elapsed time before choosing an optimisation.

The same test round found that the initial zoom detector consumed horizontal pager gestures and that reopening Peek could restore the previous pager page instead of the newly selected item. Peek now leaves one-finger horizontal gestures to the pager while the image is at normal scale, reserves panning for a zoomed image, and explicitly positions the pager at the selected URI on every entry.

Further testing found that selected items from paths with encoded characters could still fall back to the first page. Messaging folders commonly contain spaces and other encoded path characters. Passing an already encoded file URI through an encoded navigation argument and decoding it again could change the identity used for comparison. Peek selection was initially retained directly in the former singleton Gallery state. Delivery 7 now retains the selected URI and ordered viewer items in a shared MediaViewerSession; navigation carries no file URI and therefore cannot transform the selected identity, while the viewer no longer reconstructs its context from Gallery-owned state.

6. Gallery Filtering And Explainable Sources

Status: Closed after device verification.

Outcome: Users can understand and narrow a library that spans many folders without separating related photos and videos from the same activity.

Functionality:

  • Keep one mixed-media, date-grouped timeline as the default Gallery presentation.

  • Add compact Type and Location dropdown filters. Type offers All media, Photos, and Videos; Location is populated from path groups found by the retained Gallery scan.

  • Combine Type and Location filters over the retained results without rescanning, moving files, or introducing a separate result model.

  • Group location descendants through full, segment-aware path anchors: Downloads collapse at Download, camera media at DCIM, Android application storage at Android/media/<package> or an equivalent application namespace, standard Pictures and Movies containers at their next meaningful segment, and other trees at their first directory below the storage root.

  • Keep identical labels at unrelated full paths separate and qualify them in the menu rather than merging them through a textual folder-name prefix.

  • When an Android application namespace exposes an installed package label, merge a standard-container or storage-root source such as Pictures/WhatsApp or WhatsApp only when its complete source label exactly matches that verified application label. The application namespace remains the stable group key and every item retains its actual path.

  • Derive source categories and icons from visible path/folder evidence, including camera, screenshot, download, messaging, and editing/export patterns, with a generic application or folder fallback.

  • Resolve installed application labels and icons through Android’s package manager on a best-effort basis and retain successful lookups in the keyed Content Space session. Package visibility failures retain separate full-path groups and generic icons; Gallery declares only narrow visibility for recognised messaging package namespaces and does not request broad installed-application visibility or bundle branded icons.

  • Show each grouped source’s descendant-folder count, media count, and common path anchor in the Location menu. Retain the individual file’s complete parent path in the shared Properties sheet.

  • Preserve active filters while switching Spaces and use the filtered ordering in Peek so previous/next navigation matches the visible feed.

Implementation boundary: Filters are projections over shared results. They do not move files, duplicate files, claim which application created a file, or require user-defined Smart Stacks. The earlier proposal for separate top-level Photos and Videos collections was withdrawn because it breaks the chronology of mixed-media activities such as preparing a social-media post or reel.

The Peek image renderer is format-neutral. The apparent JPEG/PNG sizing difference found during this delivery came from intrinsic aspect ratio: tall PNG screenshots were fitted completely inside the viewport while ordinary camera photos naturally filled its width. Peek now fits every image to the available width, centers images shorter than the viewport, and allows normal-scale vertical scrolling for taller images. Horizontal paging remains available at normal zoom, while a zoomed image continues to reserve panning gestures.

7. Cross-Space Continuity And Shared Actions

Status: In progress. The definition/navigation and shared opening/viewer-context slices passed device verification. The shared selection/actions slice is implemented and passed device verification. Back-arrow and swipe-navigation refinements, plus clearer guidance to switch to Explorer after placing items on the operation shelf, are deferred until the migration structure is settled. The browse-engine and retained-session slice is implemented and passed device verification. The shared List/Grid presentation slice is implemented and passed device verification. The single SpaceScreen host entry, shared Search/Sort, JSON definition loader, generic Space-ID routing, and Space-keyed content-session slices are implemented and passed device verification in Explorer, Gallery, and the debug Documents Space. Content-space Sort also refreshes immediately from the shared host session. Selection and the remaining common scaffold coordination have not yet been lifted from the browser implementations. The first Phase 2 refinement batch is implemented and passed automated unit, debug-build, and release-build verification. Device verification was waived for this batch by explicit approval because the test device was unavailable: Home-origin media returns to Home, Space menu surfaces use the theme palette, browser group headings share one presentation, and the related Home, pin-picker, operation-shelf, and About polish is in place. A follow-up pin-affordance correction passed device verification: the folder picker’s explicit action now appears below its breadcrumbs, and an already pinned Explorer folder uses a crossed-pin icon for Unpin.

The Home card refinement passed physical-device verification and is closed: Spaces, Pins, and Storage use two-column cards with shared compact styling, while Pins support animated two-dimensional drag reordering and persist only the final order.

The shared browser Top App Bar refinement passed physical-device verification and is closed: Search remains visible, one overflow action opens a chip-based Browse options sheet with brand-aware selection colors, entry-point actions are capability based, and hierarchical breadcrumbs use larger semibold labels.

The Explorer grid presentation refinement passed physical-device verification and is closed. Folders use neutral compact two-column cards while files retain the three-column artwork presentation. Folder metadata is intentionally omitted because size, creation time, and direct-child count are not reliably available without extra provider traversal; richer folder summaries remain a separate architectural item.

Operation Shelf destination browsing passed physical-device verification and is closed. Both browser entry points inject an optional Browse capability which opens a Space-independent destination picker; hierarchical browsers also retain their direct Copy here or Move here action. Before selection, the second summary cell is a single primary Browse button rather than empty Destination labels; afterward Selected and Destination form an equal summary row. Transfer, Review, and Cancel use intrinsic button widths distributed like grid items, with Review and Cancel outlined. Successful picker operations return to the originating Space and continue through the shared transfer engine.

Dynamic Content format facets passed physical-device verification in both Gallery and Documents and are closed. Every Content browser derives only the document formats present in its retained result snapshot, with counts and a retained Format selection. The shared subtype filter supports PDF, Plain text, HTML, Markdown, Rich text, Word, Spreadsheet, Presentation, Ebook, AsciiDoc, JSON, and XML without a Documents-ID branch or a SpaceDefinition schema change.

AsciiDoc external opening passed emulator and physical-device verification and is closed. The shared MIME resolver treats .adoc, .asciidoc, and .asc as text/plain for Android interoperability, including older Recent records whose stored MIME is absent. On the emulator this reduced the resolver from 22 wildcard entries to two relevant, unique plain-text handlers.

Outcome: Home, Explorer, and Gallery expose their decided responsibilities while Explorer and Gallery behave like integrated Spaces over one file library rather than unrelated screens.

Functionality:

  • Add a Spaces section to Home from the loaded definition registry.

  • Remove the selected-Space meaning from Home and rename the built-in hierarchical Space from Files to Explorer.

  • Preserve the navigation state of each Space while switching.

  • Add Show in Explorer for a Gallery item and open its actual parent folder.

  • Make the Space selector available at appropriate nested Space navigation levels, but not on Home.

  • Route recent files, Pins, and Storage from Home through the shared opening and navigation rules.

  • Resolve folders, internally supported media, and Android fallback centrally; retain the originating visible item ordering and source metadata in a shared viewer session rather than Gallery state.

  • Reuse existing selection for shared actions such as Rename, Share, Properties, Open with, Copy, Move, and Trash under the same item and provider rules used in Explorer.

  • Reuse the operation shelf rather than add Gallery-specific progress UI.

  • Add Gallery Delete only through the existing move-to-Trash operation, with the same progress, undo, retention, restore, and failure behavior used by Explorer.

  • Keep permanent deletion confined to the existing Trash screen.

Acceptance focus: Users can move between visual discovery and filesystem control without losing their place or encountering different meanings for the same action. Home never appears to be an active Space, and missing Gallery actions are not encoded as a permanent Gallery policy.

Implementation sequence: Migrate incrementally rather than replacing both browser implementations in one rewrite. First introduce the built-in definition registry, Home entry section, Explorer naming, and Space-only selector while retaining the existing browsers. Then extract shared opening and origin context, selection and actions, hierarchical/content browsing engines, retained session state, and shared List/Grid presentation. Once those axes are stable, route every Space through one SpaceScreen and progressively lift Search, Sort, shared chrome, and session coordination into that host while preserving separate hierarchical and content browser bodies. Finally move definitions to validated JSON, make routing and content sessions Space-ID driven, and add Documents through JSON alone as the foundation test.

8. Release Hardening And Promotion

Outcome: Home and the two built-in Spaces can be considered for normal builds.

Functionality:

  • Test small, mixed, media-heavy, and near-limit libraries on representative Android versions and devices.

  • Verify permission, disconnected storage, empty, partial, error, and low-memory behavior.

  • Complete accessibility semantics, focus order, touch targets, and screen-reader descriptions.

  • Measure scan latency, scroll smoothness, thumbnail memory, and context restoration.

  • Confirm that the Home Spaces section, Explorer/Gallery selector, and migration from the prototype Files label are clear.

  • Remove the debug gate only after the release evidence below is satisfactory.

9. Additional And Custom Spaces

Outcome: The stable built-in model may expand to Documents or user-defined interests without weakening Explorer and Gallery.

The debug Documents proof uses the shared Documents file-type rule: text MIME types, PDF, and recognised document extensions such as common office, CSV, and ebook formats. It does not infer membership from a Downloads folder or from a possible scan origin. Product promotion of that Space still requires evidence and polish. Possible later work includes:

  • creator-oriented or audio-oriented recipes;

  • user-created Spaces with explicit included folders, browse type, content membership, and presentation defaults; and

  • optional local suggestions based on explicit choices and meaningful opens.

This component reintroduces the discovery questions that were withdrawn for Explorer and Gallery. Additional Spaces should have evidence of a distinct recurring job and must not be justified only by a broad persona stereotype. It must extend the shared definition axes rather than introduce a separate simple/composed template taxonomy.

Evidence Required For Release

User interviews are not required to prove that Explorer and Gallery should exist. The following evidence is required to promote the implementation from the debug lab:

  • Switching is discoverable and users understand that Explorer and Gallery show the same underlying files.

  • Home is understood as the application dashboard rather than another Space, and its Recent, Pins, and Storage entries open in the appropriate context.

  • Gallery finds expected media across representative Camera, Screenshots, Downloads, messaging, and export folder layouts.

  • Timeline ordering and source labels are understandable and explainable.

  • Repeated switching restores context without unnecessary full rescans.

  • Large libraries remain responsive and memory-safe; numeric performance thresholds should be set after baseline measurement rather than invented in advance.

  • Peek and shared actions behave consistently with the existing file infrastructure.

  • Users encounter the same file-action meanings and eligibility in every Space, can distinguish Remove from Space from moving a file to Trash, and no Space bypasses Trash for permanent deletion.

  • Permission, privacy, accessibility, and failure states are credible enough for a normal file-management surface.

Structured usability sessions, real-device dogfooding, and targeted interviews may provide this evidence. Product analytics or cloud profiling are not assumed.

Open Refinements

The following decisions can be made during their owning deliverables:

  • exact capture-date fallback rules;

  • whether filenames appear permanently in the Gallery grid;

  • how messaging and editing/export folders are grouped and labelled in the Location filter;

  • whether the selected Space persists across application restarts;

  • whether selecting a Space from Home restores its last context or starts at its root after a process restart;

  • when the selector should appear in nested file navigation; and

  • whether the vertical icon rail offers enough value over the dropdown.

These refinements must not block the earlier foundations unless testing shows that an assumption makes the current component unusable.

Delivery Convention

For every code-bearing Spaces deliverable:

  1. Update this document’s status and any changed decisions.

  2. Add focused unit or UI tests for shared rules and behavior.

  3. Run the relevant unit tests, assemble the debug application, and compile the release variant to ensure the lab gate does not break production code.

  4. Make the assembled debug APK available from its build-output location for device verification; do not copy it to the tracked artifacts directory unless explicitly requested.

  5. After device verification, commit the implementation, documentation, and tests together. Push only when explicitly requested.

A documentation-only clarification does not require rebuilding an unchanged APK.