` | | CredentialFileField | `fileImporter` + drop + paste | `FileOpenPicker` + drop | `fileImporter` | `OpenDocument` | `GtkFileDialog` + drop | `` + drop + paste | | MultiSelect | `Table` selection | `ListView SelectionMode=Extended` | `EditButton` / selection | selection mode | `GtkMultiSelection` | `aria-multiselectable` grid | --- # 00-shared/COPY-AND-STATES.md Source: https://compositecode.github.io/substratalapps-applications-specs/spec/00-shared/COPY-AND-STATES.md ## Copy, States & Error Messages Use these strings verbatim (localize via each platform's string catalog). Sentence case on every platform. ### Status and value labels | Domain value | Label | Tile / row helper text | |---|---|---| | entitlement `active` | Active | — | | `scheduled` | Scheduled | Starts {date} | | `disabled` | Turned off | Turned off by an administrator | | `expired` | Expired | Access ended {date} | | `revoked` | Revoked | Access was removed | | `none` | No access | Get access · (standard app on Free) Included with Standard | | source `purchase` / `trial` / `admin_grant` / `org_seat` | Purchased / Trial / Granted by admin / Via {org name} | | | source `free` | Free | Managed by Substratal | | source `subscription` | Standard | Your subscription · or · Via {org name}'s subscription | | app `access_tier` `free` / `standard` | Free / Standard | | | user `plan` `free` / `standard` | Free / Standard | | | subscription `active` / `trialing` / `past_due` | Active / Trial / Payment issue | — / Trial ends {date} / We couldn't charge your card. Update it in Manage billing. | | subscription `canceled` / `unpaid` / `incomplete` / `incomplete_expired` / `paused` | Canceled / Unpaid / Checkout not finished / Checkout expired / Paused | | | `cancel_at_period_end: true` | Ends {date} | Standard access continues until {date}. | | user `invited` / `suspended` / `deleted` | Invited / Suspended / Deleted | | | member scope `all_members` / `allowlist` / `denylist` | Everyone in the organization / Only selected members / Everyone except selected members | | | tier `shared` / `isolated` / `dedicated_region` | Shared / Isolated / Dedicated region | | | device `active` / `inactive` | On / Off | | | device `inactive_reason` `unregistered` / `session_revoked` / `user_suspended` / `user_deleted` / `stale` / `limit` / `credential_removed` | Notifications turned off on the device / Signed out / Account suspended / Account deleted / Not opened in 9 months / Replaced by a newer device / Push setup removed by the app | | | notification `state` `unread` / `read` / `archived` | Unread / Read / Archived | | | notification `priority` `high` | Important | | | notification `source` `platform` | Substratal | | | push `status` `queued` / `sent` / `failed` / `skipped` | Sending / Pushed to {n} devices / Couldn't push / Not pushed | | | `skip_reason` `push_not_requested` / `push_disabled` / `no_devices` / `no_credentials` / `credential_failed` / `expired` | Sent to inbox only / Notifications are off for this app / No devices to push to / Push isn't set up for this app / Push setup needs attention / Expired before it could be sent | | | push credential `active` / `failed` | Active / Needs attention | | ### Confirmations | Action | Title | Body | Destructive button | |---|---|---|---| | Access off | Turn off {app} for {name}? | They'll lose access right away. You can turn it back on later. | Turn off | | Access off (platform-managed) | Turn off {app} for {name}? | This access comes with their {Free plan / Standard subscription}. It stays off until you turn it back on, even if their plan changes. | Turn off | | Remove grant (<24h) | Remove this grant? | Use this only for a grant made by mistake. It won't appear as revoked — it'll be gone. | Remove | | Suspend user | Suspend {name}? | They'll be signed out everywhere, stop receiving push notifications, and can't sign in until reactivated. | Suspend | | Delete user | Delete {name}? | Their account is deactivated. An admin can restore it. | Delete | | Delete my account | Delete your account? | Your account is deactivated now and permanently erased on {date}. Until then, support can cancel it. | Delete account | | Delete my account (paying) | Cancel your subscription first? | You have a Standard subscription. Deleting your account doesn't stop billing — cancel it in Manage billing. | Manage billing (secondary: Delete anyway) | | Rotate API key | Rotate this key? | The current secret stops working immediately. Update every service that uses it first. | Rotate now | | Revoke API key | Revoke {key name}? | This can't be undone. | Revoke | | Rotate webhook secret | Rotate signing secret? | Both the old and new secret are valid for 24 hours. | Rotate | | Sign out everywhere | Sign out of all other sessions? | Every other device will need to sign in again and will stop receiving push notifications until then. | Sign out | | Remove member | Remove {name} from {org}? | They lose any app access that came from this organization, including its Standard subscription. | Remove | | Change org coverage | Update who's covered? | {n} people gain Standard and {m} lose it right away. Billing changes on the next daily sync. | Update | | Remove device | Stop notifications on {device}? | That device stops getting push notifications until it's set up again. | Remove | | Turn off push (this device) | Turn off notifications on this device? | You'll still see everything in your Inbox. | Turn off | | Remove push credential | Remove {APNs / FCM / Web Push}? | {app} stops sending push notifications through {provider}. (Web Push: every browser that signed up for notifications has to sign up again.) | Remove | ### Empty states | Screen | Title | Body | Action | |---|---|---|---| | Home (no apps) | No apps yet | When someone gives you access to an app, it shows up here. | — | | Inbox | You're all caught up | New alerts and updates from your apps show up here. | — | | Inbox (Archived) | Nothing archived | Notifications are kept for 90 days. | — | | Devices | No devices yet | Turn on notifications to get alerts on this device. | Turn on | | Organizations | No organizations | Create one to manage a team and share apps. | New organization | | Users (search miss) | No results for "{q}" | Check the spelling or search by user ID. | Clear search | | API Keys | No API keys | Create a key so your backend can call Substratal. | Create key | | Webhooks | No webhooks | Get notified when access changes. | Add webhook | | Push credentials | Push isn't set up | Add APNs, FCM or Web Push so this app can send notifications. | Add provider | | Audit | No events in this range | Try a wider date range. | — | | Forbidden | You don't have access to this | Ask an administrator if you think you should. | — | ### Upsell and plan copy | Where | Copy | |---|---| | Standard tile on Free | Included with Standard | | Upsell sheet | Get every app and service for $6 a month. · Upgrade to Standard | | Org upsell | Cover your team: $6 per person per month. You choose who's included. | | Covered by org | Your organization covers you with Standard. | | Double coverage | Your organization already covers you. You can cancel your own subscription in Manage billing. | | Waiting after checkout | Finishing up… This usually takes a few seconds. | | Downgraded | Your Standard access ended on {date}. Your data is kept and comes back when you subscribe again. | | Business / Enterprise | Need more? Contact sales for business and enterprise plans. | ### Error code → message | `error.code` | HTTP | Message | |---|---|---| | `unauthenticated` | 401 | Your session ended. Sign in again. | | `session_revoked` | 401 | You were signed out from another device. | | `forbidden` | 403 | You don't have permission to do that. | | `not_found` | 404 | This item doesn't exist or was removed. | | `validation_failed` | 422 | (field-level from `details`) | | `not_unique` | 409 | That {field} is already in use. | | `email_taken` | 409 | An account with this email may already exist. Sign in or reset your password. | | `version_conflict` | 409 | This changed since you opened it. Reload · Re-apply | | `entitlement_already_exists` | 409 | This person already has access. View it | | `entitlement_platform_managed` | 409 | This access is managed by Substratal. You can only turn it off or back on. | | `entitlement_required` | 403 | Access to this app is turned off. | | `invalid_source` | 422 | Free and Standard access can't be granted by hand. | | `subscription_exists` | 409 | You already have a subscription. Manage billing | | `no_billing_account` | 409 | There's no billing account yet. Subscribe first. | | `plan_requires_sales` | 422 | Business and enterprise plans are arranged with sales. Contact sales | | `subscription_not_found` | 404 | This organization doesn't have a subscription yet. Subscribe | | `member_override_not_a_member` | 422 | {name} isn't an active member of this organization. | | `test_mode_billing_unavailable` | 409 | Billing isn't available in test mode here. | | `billing_unavailable` | 503 | Billing is temporarily unavailable. Try again in {n}s. | | `push_credential_exists` | 409 | This provider is already set up. Edit it instead. | | `invalid_push_credential` | 422 | That key file isn't valid for {provider}. | | `push_not_configured` | 409 | Push isn't set up for this app yet. | | `invalid_device_token` | 422 | (silent; retry registration on next launch) | | `reserved_category` | 422 | Categories starting with security., account. or billing. are reserved. | | `notification_too_large` | 422 | This notification is {n} bytes over the 4 KB push limit. | | `invalid_status_transition` | 409 | That change isn't allowed. | | `user_token_required` | 400 | Sign in as a person to do this. | | `tenant_suspended` | 403 | This workspace is suspended. Contact support. | | `destructive_operation_restricted` | 403 | This key can't perform destructive actions. | | `idempotency_key_reused` | 422 | That request was already sent with different details. Try again. | | `rate_limited` | 429 | Too many attempts. Try again in {n}s. (Notifications to one person: That person has had too many notifications from this app this hour.) | | `not_implemented` | 501 | (never shown — the feature is hidden behind its flag) | | `service_unavailable` | 503 | Substratal is briefly unavailable. Retrying in {n}s. | | `internal_error` | 500 | Something went wrong on our side. Request ID {id} | | `plan_limit_reached` | 409 | Reserved by the API for future business plans; nothing returns it today. If seen: You've reached a plan limit. Contact sales | Always show the `X-Request-Id` (or equivalent) in a "Details" disclosure for 5xx errors so support can trace it. ### Push notification text (platform alerts shown by the Hub) The API supplies title and body; the Hub supplies actions per category: | Category | Actions on the notification | |---|---| | `security.new_sign_in` | It was me · Review sessions | | `security.password_changed`, `security.email_changed`, `security.mfa_disabled`, `security.session_reuse_detected` | Secure my account | | `account.organization_invitation` | Accept · View | | `account.access_granted` | Open {app} | ### Loading - Lists: skeleton rows (shape of the real row) after 300 ms; never a full-screen spinner for list refreshes. - Actions: button shows inline progress and is disabled; the rest of the screen stays interactive. --- # 00-shared/ACCESSIBILITY.md Source: https://compositecode.github.io/substratalapps-applications-specs/spec/00-shared/ACCESSIBILITY.md ## Accessibility & Internationalization Target: **WCAG 2.2 AA** on every platform, plus each platform's own accessibility guidance. ### Requirements (all platforms) | Area | Requirement | |---|---| | Screen readers | VoiceOver (macOS/iOS, Safari), Narrator (Windows), TalkBack (Android), Orca (Linux via AT-SPI), NVDA/JAWS (Web on Windows). Every control labeled; StatusBadge reads "{App}, {status label}". AccessSwitch reads "Access to {app}, on/off, switch". | | Status | Never color-only (icon + text label). Badge text meets 4.5:1 in every theme. Theme contrast for every theme is tabulated in THEMES.md §4. | | Text scaling | Dynamic Type (iOS/macOS where applicable) up to AX5; Android font scale up to 200 %; Windows text scaling 225 %; GNOME Large Text. Grids reflow to fewer columns; no truncation of status labels. | | Keyboard | Full keyboard operation on desktop, iPad and Android with hardware keyboards, and Web (WAI-ARIA Authoring Practices patterns for grid, tabs, menu, dialog, combobox). Visible focus ring (platform native). Tab order follows reading order. Shortcuts listed in each platform spec. | | Targets | ≥ 44×44 pt (Apple), 48×48 dp (Android), 40×40 epx (Windows touch: 44), 34 px min (GNOME). | | Motion | Respect Reduce Motion / Animations off; toggles and sheets cross-fade instead of slide. | | Contrast modes | Windows High Contrast themes (use `SystemColor*` resources, no hard-coded colors), macOS/iOS Increase Contrast, GNOME High Contrast, Android high-contrast text, Web `prefers-contrast` / `forced-colors`. | | Timeouts | MFA challenge countdown announced at 60 s and 10 s; user can request a new challenge. | | Secrets | Secrets are selectable text, not images; screen readers can read them character by character. | ### Internationalization - All strings externalized: String Catalogs (`.xcstrings`) on Apple, `.resw` on Windows, `strings.xml` on Android, gettext `.po` on Linux. - Dates/times rendered in the user's Profile `timezone` and `locale` (from `GET /users/{id}/profile`), falling back to OS settings. Show relative times in lists ("3 min ago") with absolute time on hover/long-press. - Support RTL layout mirroring (Arabic, Hebrew): icons with direction (chevrons, arrows) mirror; app icons and QR codes do not. - IDs (`usr_…`) are never localized or mirrored. ### Gesture and shortcut parity Every gesture (swipe, long-press, pinch, drag) and every keyboard shortcut is an accelerator for an action that also has a visible button or menu item reachable by keyboard and screen reader. Screen-reader users get the same actions as **custom actions** (iOS/macOS `accessibilityActions`, Android `customActions`, Windows `AutomationProperties` + context menu, GTK accessible actions, Web `aria-*` + menu button). ### Focus management - Opening a sheet/dialog moves focus to its first field (or title for confirms); closing returns focus to the invoker. - After a destructive action removes a row, focus moves to the next row (or the list heading if empty). - Route changes move focus to the page heading and announce the page title. ### Notifications - The unread count is part of the Inbox item's accessible name ("Inbox, 3 unread"), not color or a dot alone. - New notifications arriving while the app is open are announced politely once ("New notification from Timetrack"), never repeatedly; security alerts use assertive announcement only when the Inbox is focused. - Notification actions (Accept, Review sessions) are also available inside NTF-02, so people who dismiss system notifications or use switch access can reach them. --- # 00-shared/NON-FUNCTIONAL.md Source: https://compositecode.github.io/substratalapps-applications-specs/spec/00-shared/NON-FUNCTIONAL.md ## Non-Functional Requirements (client side) ### 1. Performance budgets | Metric | Desktop native | Mobile native | Web | |---|---|---|---| | Cold start → interactive Home (cached) | ≤ 1.0 s | ≤ 1.5 s (mid-tier device) | LCP ≤ 2.5 s on 4G mid-tier phone; ≤ 1.2 s repeat visit (service worker) | | Navigation to a cached screen | ≤ 100 ms | ≤ 150 ms | ≤ 100 ms (client routing) | | Input feedback (press, toggle) | next frame (≤ 16 ms) | next frame | INP ≤ 200 ms (p75) | | List scroll | 60 fps (120 on ProMotion/high-refresh) | 60/120 fps, no jank | no long tasks > 50 ms during scroll | | Layout stability | — | — | CLS ≤ 0.1 | | Search results (server) | show skeleton at 300 ms | same | same | | Launch app (APP-03) | token minted + handoff ≤ 1 s p75 | ≤ 1.2 s | ≤ 1 s | | Push tap → target screen | ≤ 1 s warm, ≤ 2 s cold | ≤ 1.5 s warm, ≤ 2.5 s cold | ≤ 1.5 s (service worker focuses/opens the client) | | Badge freshness | ≤ 60 s while running (polling) | on push + foreground | on push + visibility change | | Return from Stripe → plan shown | ≤ 30 s (poll) | ≤ 30 s | ≤ 30 s | | Bundle / binary | — | ≤ 40 MB download | ≤ 170 KB JS (gzip) initial route; route-split the rest | | Memory | ≤ 250 MB with 10k-row table | ≤ 200 MB | — | Large collections (users, audit, deliveries) must be virtualized on every platform. ### 1a. Platform behavior the clients rely on - Push dispatch p95 < 10 s from send to first provider attempt; providers may still delay or drop — the inbox is the source of truth. - Inbox retention 90 days; delivery details 30 days; inactive devices deleted after 30 days; devices go stale after 270 days without re-registration (clients re-register daily on launch). - Audit hot window: 1 year for every Tenant. - Stripe coverage changes land via webhook, usually within seconds of checkout; org quantity syncs daily at 00:15 UTC. ### 2. Reliability - No crash rate above 0.2 % of sessions (native); no unhandled promise rejections (web). - Every write is idempotent from the client's point of view (Idempotency-Key, If-Match). - Network loss mid-write: the control returns to its prior state with an error; the user can retry; the retry reuses the same Idempotency-Key. ### 3. Security & privacy See CLIENT-ARCHITECTURE §9. Additionally: - Admin screens show other people's personal data: no persistent caching, hide in app switcher/screenshots where supported, auto-lock after 15 min idle (configurable by org policy later). - Data export files (ACC-07, USR-03) are written only where the user chooses; no copies left in temp/cache. - Privacy manifests / data-safety forms: collected data = email, name, user ID, device/session info, **push device tokens** (sent to Substratal and Apple/Google/browser push services, which are sub-processors), purchase history (Stripe, outside the app), usage analytics (opt-out). - Notification content is never logged, analyzed or added to by the client; lock-screen previews follow the OS setting. ### 4. Localization - Launch locales: en-US. Architecture must support RTL and pluralization from day one. - Strings externalized with keys mirroring screen IDs (`ACX03.title`, `COPY.confirm.access_off.body`). - Dates, times, numbers, lists and relative times formatted with the platform locale APIs using the profile's `locale` and `timezone` (fallback: OS). Times on admin screens show the viewer's zone, with UTC on hover/long-press. - Pseudo-localization build (+40 % length, accented) must lay out without truncating status labels or buttons. ### 5. Accessibility WCAG 2.2 AA plus platform guidelines — see ACCESSIBILITY.md. ### 6. Supported platforms | App | Minimum | Primary test matrix | |---|---|---| | macOS | macOS 15 | 15, 26 · Apple silicon + Intel | | Windows | Windows 10 22H2 (WinAppSDK) | Windows 11 24H2/25H2 · 100–200 % scaling · touch laptop | | iOS/iPadOS | iOS 17 | iPhone SE, iPhone 17, iPhone 17 Pro Max, iPad mini, iPad Pro 13" with keyboard + Pencil | | Android | API 26 (8.0) | Pixel 6a, Pixel 10, Samsung foldable (folded/unfolded), 10" tablet, ChromeOS | | Linux | GNOME 46+ (libadwaita 1.5+) | Ubuntu 24.04/26.04, Fedora latest, KDE Plasma (Flatpak) | | Web | Last 2 versions of Chrome, Edge, Safari, Firefox; Safari iOS 17+; Samsung Internet | phone 360–430 px, tablet 768–1180 px, desktop 1280–2560 px | ### 7. Quality gates per release - Unit tests on domain services and Capabilities (every persona × every nav item). - Contract tests against the API's staging environment generated from `openapi.yaml`. - UI tests for the 11 flows in UX-FLOWS.md on every platform. - Accessibility automated checks (XCTest a11y audits, Accessibility Insights, Espresso/Compose checks, axe-core) + manual screen-reader pass of the 11 flows. - Performance traces against the budgets above on the lowest test device. --- # 00-shared/OPEN-QUESTIONS.md Source: https://compositecode.github.io/substratalapps-applications-specs/spec/00-shared/OPEN-QUESTIONS.md ## Open Questions & Spec Gaps Gaps between the API (spec v1.4.0) and what the Hub clients need. Each has a working assumption so building can start; the "Status" column says what changed with v1.4.0. | # | Topic | Gap | Working assumption | Affects | Status | |---|---|---|---|---|---| | 1 | Avatar upload | API stores `avatar_url` only; no upload endpoint | A small signed-URL upload service, then PATCH the URL. Until it exists, avatar editing is hidden (initials shown). | ACC-01, APL-02 icon | Open | | 2 | Push on Windows and Linux | The API's providers are APNs, FCM and Web Push only — no WNS, and Linux desktops have no push service | Windows and Linux poll `unread-count` / new inbox items (60 s while running, opt-in background) and raise **local** notifications and badges. Ask the API team whether to add a `wns` provider. | NTF-*, Windows, Linux | **Resolved for iOS/macOS/Android/Web by the API's Push Notifications; open for Windows (WNS)** | | 3 | Hub as an Application | Devices must belong to an Application | The Hub is the first-party Application `app_hub`: `access_tier: free`, `receives_platform_notifications: true`, `visibility: internal`, with APNs/FCM/Web Push credentials. iOS and macOS share one bundle id (Universal Purchase) because an Application has one APNs credential with one `topic`. Confirm with the API team that one APNs topic per Application is intended, or ask for multiple topics. | CLIENT-ARCHITECTURE §2, §6 | **Changed** — was "Hub is not an Application" | | 4 | SSO & passkeys | SSO callback returns 501; no WebAuthn endpoints | Buttons hidden behind `sso` / `passkeys`. | AUTH-01 | Open | | 5 | Role holders | No `GET /users?role_id=` filter | "People with this role" hidden on ROL-02. | ROL-02 | Open | | 6 | Bulk operations | No bulk endpoints except `notifications/mark-read` | Bulk actions run one request per row (max 4 in parallel) with per-row results. Inbox "mark all read" uses the real bulk endpoint. | USR-01, ACX-05, NTF-01 | Partly resolved | | 7 | Session and device names | `Session` has `user_agent` + `ip_address`; `Device` has an optional `name` | Hub sends a descriptive `User-Agent`, and registers devices with a readable `name` ("Dana's iPhone", "Chrome on macOS") the person can rename in NTF-03. | ACC-04, NTF-03 | Partly resolved | | 8 | Locale list | No endpoint listing locales/time zones | Use the platform's locale and IANA lists. | SET-01 | Open | | 9 | App launch contract | How each app receives the app token isn't standardized | `launch_url` with `#app_token=` by default; per-app override client-side until the API adds a field. | APP-03 | Open | | 10 | Store payment rules | **Standard is now a consumer subscription ($6/user/month) that unlocks apps** — App Store and Play generally require in-app purchase for digital subscriptions used in the app | Mobile shows plan status and "Manage billing"; the **Upgrade** button is flag-gated per store (`billing_upgrade_ios`, `billing_upgrade_android`) and defaults **off** until legal/policy review (US external-purchase link entitlement, other regions' rules, or adding StoreKit / Play Billing products that the API would need to recognize). Web, macOS (outside the Mac App Store build), Windows and Linux upgrade via Stripe Checkout. | BIL-01/02/03 | **Changed** — was a B2B developer plan | | 11 | Audit export | Phase 3 | Hidden behind `audit_export`. | AUD-01 | Open | | 12 | Org suspension by admins | Needs `organizations.manage` | Org admins see no suspend control. | ORG-08 | Open | | 13 | Test mode in UI | `test_mode` on users, keys, webhooks, devices, notifications, subscriptions | Developer builds expose test-mode sign-in; test-mode devices register with APNs `sandbox`; test-mode checkout needs Stripe test mode (`409 test_mode_billing_unavailable` otherwise). | AUTH-01, KEY-*, NTF-*, BIL-* | Extended | | 14 | Web session storage | No OS secure store in browsers | Same-origin BFF holds the refresh token in an HttpOnly cookie. | Web | Open | | 15 | CORS | Web app needs `Authorization`, `Idempotency-Key`, `If-Match` allowed and `ETag`, `Retry-After`, `Audit-Hot-Window-Start` exposed | Confirm API CORS config for `https://dashboard.substratalapps.com`. | Web | Open (header list extended) | | 16 | Notifications not built yet | Every Notifications operation returns `501 not_implemented` today | Ship NTF-* and APL-07 behind `notifications` / `push` / `push_credentials` flags; 501 flips them off. | D13, APL-07 | New | | 17 | Erasure vs. billing | Deleting an account doesn't cancel a Stripe subscription | ACC-08 warns subscribers and links to Manage billing first. Ask the API team whether erasure should cancel at period end. | ACC-08 | New | | 18 | Annual plans / Standard trial | DECISIONS #31 still open | No UI; BIL-01 copy avoids promising either. | BIL-01 | New | | 19 | Price display | Price shown before a subscription exists isn't returned by any endpoint | Show "$6 per month" from remote config (matches Pricing), and `unit_amount` once a subscription exists. | BIL-01/02 | New | | 20 | Hub access disabled | An admin can disable someone's `app_hub` Entitlement | They can still sign in to the Hub (platform session) but can't register devices (403) — inbox-only mode with an explanation in NTF-03. | NTF-03/04 | New | | 21 | Notification actions from the lock screen | Accepting an org invitation from a notification needs a valid platform session | Mobile/macOS require device unlock and refresh the session in the background; if refresh fails, open the app to ORG-09. | ORG-09, NTF-02 | New | | 22 | Theme choice storage | `Settings` only has `theme` (light/dark/system); there is no field for which light or dark theme | Store `appearance.light_theme` / `appearance.dark_theme` as `app_hub` per-app settings, which requires both keys (string enums, defaults `moss-paper` / `forest-floor`) in `app_hub`'s `settings_schema`. Until then, keep them on the device. Alternative: add `light_theme` / `dark_theme` to `Settings`. | SET-01, THEMES.md | New |