diff --git a/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md b/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md index f0ecbce..c1b7770 100644 --- a/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md +++ b/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md @@ -30,8 +30,10 @@ Review the actual change rather than only checking whether files exist: - Perform the mandatory [networking check](#audit-networking) for network implementation, dependency changes, and networking-policy adoption. - Check SwiftUI composition, narrow inputs, local versus durable state, localization, accessibility, and safe deterministic previews where applicable. - For each new or changed SwiftUI `ScrollView`, apply the shared [scrolling guidance](../../../Guidelines/Swift/SwiftUI.md#scrolling): verify `.scrollBounceBehavior(.basedOnSize)` covers its scrolling axes on supported deployment targets, including scroll views in modal sheets. Check the modifier's environment scope around nested scrollables and require a documented interaction reason for a different bounce behavior. +- Perform the mandatory [SwiftUI-first implementation check](#audit-swiftui-first-implementation) before accepting UIKit/AppKit code or interoperability in a SwiftUI application. - Perform the mandatory [native-component and presentation decision check](#audit-native-components-and-presentation) for changed SwiftUI controls and presentation behavior. - Perform the mandatory [system-control placement check](#audit-system-control-placement) for changed navigation, toolbars, dismissal controls, and window chrome, including affected UIKit/AppKit wrappers. +- Perform the mandatory [user-experience check](#audit-user-experience) for changed task continuity, lifecycle-driven UI, automatic refreshes, and loading behavior, regardless of implementation framework. - Perform the mandatory [animation and image-rendering check](#audit-animation-and-image-rendering) for changed visual transitions, reusable control styles, and dynamic image paths, including directly affected consumers. - Perform the [Reduce Motion check](#audit-reduce-motion) for affected motion and for Reduced Motion support declarations. - Perform the [tvOS current-user identity check](#audit-tvos-current-user-identity) when changed behavior relies on selected-profile preferences, CloudKit accounts, or personal store binding. @@ -92,6 +94,27 @@ Use these scenarios to distinguish valid outcomes: | Adoption discovers untouched legacy HTTP | Migrate within scope or record an explicit owner-approved deferral; no full-compliance claim | | No networking implementation or dependency change, and no policy adoption | Evidence-backed not applicable | +## Audit SwiftUI-first implementation + +Apply the authoritative [SwiftUI-first policy](../../../Guidelines/Swift/SwiftUI.md#swiftui-first-implementation) to the completed change and directly affected UI boundaries: + +1. Inspect UIKit/AppKit imports and actual UI responsibilities, view/controller subclasses, `UIViewRepresentable`, `UIViewControllerRepresentable`, `NSViewRepresentable`, `NSViewControllerRepresentable`, hosting controllers, controller introspection, and presentation or animation bridges. Follow wrappers and relevant dependency calls to their implementation; a SwiftUI-facing API or an Apple-native presenter does not establish compliance. Include directly affected existing bridges rather than grandfathering them. Do not expand a focused audit into an unrelated application rewrite. +2. For each interoperability boundary, identify the exact requirement and supported deployment targets. Check the evaluated public SwiftUI alternatives, including compositions of presentation modifiers, state, layout, transitions, animations, and materials. Require current documentation or reproducible evidence that SwiftUI cannot meet the requirement. A failed first attempt, visual preference, convenience, or familiarity with UIKit is insufficient. +3. When SwiftUI can implement the behavior, require the in-scope implementation to use SwiftUI. Do not accept a convenience exception or ask the owner to approve one. UIKit/AppKit interoperability without a demonstrated SwiftUI capability gap blocks audit completion, even when the underlying API is native or another native-component check passes. +4. For a genuine gap, verify explicit repository-owner approval before implementation and the durable consumer exception required by the policy. Verify the approved scope, lifecycle/state ownership, validation, and revisit condition. Approval alone does not replace capability-gap evidence. Missing evidence, approval, documentation, or boundary validation blocks completion; neither this audit nor an agent's implementation choice grants an exception. +5. Keep approved interoperability limited to the missing capability. Check that it does not recreate unrelated SwiftUI navigation, presentation, environment propagation, or application state in a parallel controller hierarchy. Apply the existing native-component, system-control, lifecycle, and runtime-evidence checks to the affected boundary as well. Record applicability, inspected paths, alternatives, exception evidence, and validation in the handoff. + +Use these scenarios to distinguish valid outcomes: + +| Scenario | Audit outcome | +| --- | --- | +| Public SwiftUI APIs implement the required UI | Use SwiftUI; accept with applicable validation | +| UIKit controller or representable added for a transition SwiftUI can express | Block until the in-scope implementation uses SwiftUI | +| UIKit hidden inside a SwiftUI modifier or dependency without gap evidence | Block; trace and apply the same requirement | +| Missing SwiftUI capability demonstrated, owner-approved, documented, and narrowly bridged | Accept only the approved boundary with validation | +| Owner approval exists but SwiftUI capability-gap evidence is absent | Block; approval does not establish impossibility | +| No SwiftUI application or interoperability boundary is in scope | Record not applicable; do not invent a migration | + ## Audit native components and presentation Apply the authoritative [SwiftUI native-component policy](../../../Guidelines/Swift/SwiftUI.md#native-components-and-presentation) to changed controls and presentation flows: @@ -112,10 +135,32 @@ Apply the authoritative [system control placement policy](../../../Guidelines/Sw 4. For changed navigation or toolbar behavior, record supported target/OS and targeted runtime actions and outcomes: Back navigates, dismissal closes the intended presentation, and cancellation/confirmation retain their actual semantics. Check relevant layout direction, accessibility, keyboard/remote, and gesture behavior. When presentation lifecycle also changes, apply the existing [interaction evidence requirements](../../../Guidelines/Swift/SwiftUI.md#required-interaction-evidence) to that affected flow. Documentation-only policy changes do not require simulator evidence. 5. An unjustified placement override or missing relevant interaction evidence blocks audit completion. Report the exact control, ownership, violated policy, and missing evidence; do not report an Apple-selected side as a defect. +## Audit user experience + +Apply the canonical [User Experience guide](../../../Guidelines/Design/UX.md) to changed behavior and directly affected flows in apps and games, regardless of implementation framework. Record an evidence-backed `not applicable` for changes without these behaviors; do not expand into unrelated flows. These are implementation acceptance checks; they do not change the PR review contract's P0/P1 reporting threshold. + +1. Identify the current task, recoverable input and presentation context, and every relevant automatic-work trigger. Trace what makes that work necessary now, what the user sees, and what happens if the trigger arrives while a flow is active. A foreground callback or a retained draft alone is not proof of a good experience. +2. Exercise background and foreground transitions during affected editing, entry, selection, search, and presentation flows. Require preserved task context and the absence of unnecessary overlays, focus loss, or navigation resets. Verify cold loading and actual access invalidation separately; the continuity rule must not suppress necessary protection. +3. Trace skipped refreshes through subsequent save, cancellation, and dismissal. Require runtime outcomes plus deterministic tests or event evidence when needed to prove that closing a flow cannot replay an unrelated skipped attempt. Distinguish synchronization caused by a real mutation and a new independent refresh trigger from catch-up work. +4. For intentionally deferred required work, inspect the consumer's durable reason, eligibility, need recheck, and expected presentation against the canonical guide. Convenience or a desire to eventually process every lifecycle callback is insufficient. Verify that a result arriving after the user starts a new task does not interrupt that task. +5. Require runtime evidence for applicable scenarios in the guide: platform/OS, app revision, initial state, trigger, actions, and observed result. Accept recorded manual verification where automation is unavailable; static screenshots and successful tests alone do not prove visible continuity. Documentation-only policy changes require scenario walkthroughs rather than consumer runtime evidence. +6. Unnecessary interruption, unjustified catch-up refresh, lost context, or missing applicable evidence blocks audit completion. Record the violated guide section and exact correction or missing evidence. Fix authorized in-scope behavior and reconcile durable product documentation; do not silently rewrite a consumer's documented freshness requirement. + +| Scenario | Audit outcome | +| --- | --- | +| An editor survives activation but a routine loading overlay covers it | Blocked; retained input does not justify interrupting the task | +| A busy foreground attempt is skipped, then dismissal starts its reload | Blocked until the unjustified catch-up path is removed | +| Saving synchronizes the actual edit, without replaying the skipped attempt | Accepted with trigger and interaction evidence | +| A later eligible activation starts a newly assessed refresh | Accepted when the current task and loading behavior satisfy the guide | +| Revoked access interrupts a flow for a documented safety reason | Accepted with prompt access protection and appropriate recovery evidence | +| Code claims to skip a refresh, but dismissal and visible continuity were not exercised | Incomplete pending applicable evidence | + ## Audit animation and image rendering Apply the authoritative [animation policy](../../../Guidelines/Swift/SwiftUI.md#animation) and [image-rendering policy](../../../Guidelines/Swift/SwiftUI.md#image-rendering) to changed components and directly affected consumers; do not expand the audit into unrelated screens. +For motion, also apply the framework-independent [Animations guide](../../../Guidelines/Design/Animations.md), including in non-SwiftUI app and game interfaces. Exercise its applicable acceptance scenarios: inspect movement of the complete component and coordinated container resizing, entrance and exit direction and concealment, incoming and outgoing feedback, unchanged neighbours, and reversals before completion. Require normal-speed runtime observation; inspect intermediate frames when a defect is suspected. Record any intentional choreography or immediate feedback rationale. An unresolved violation of these experience requirements blocks audit completion even when animation modifiers or settled states appear correct; use the canonical guide to direct the correction. + 1. Identify each meaningful visual transition, its owner, and its intended animation or justified immediate feedback. Inspect stable view identity and transaction scope, including simultaneous changes and surrounding layout animations; an `.animation` modifier alone is not evidence of correct scope. Accept appropriate native feedback without additional animation. 2. Verify reusable defaults without caller-added animation. Exercise enabled to disabled and disabled to enabled, ordinary presses, rapid reversals, and relevant show/hide behavior. Confirm enabled state, hit-testing, accessibility state, and action availability change immediately while appearance animates. 3. Inspect affected image paths for repeated preparation, oversized drawable content, unstable identity, unbounded caches, and stale publication. Verify derivative refresh for changed source or presentation requirements, bounded intermediate memory, preservation of authoritative originals, and rejection of stale results after replacement, cancellation, or removal. Use applicable deterministic tests for asynchronous races alongside interaction evidence. @@ -131,6 +176,10 @@ Use these scenario walkthroughs when evaluating the check: | Custom main-button style changes colors abruptly | Blocked until shared behavior is corrected or an intentional immediate transition is justified | | Shared style animates both directions; actions remain immediate | Accepted with runtime evidence, including ordinary presses and rapid reversals | | Appropriate native control already supplies feedback | Accepted without additional animation | +| A button label arrives before its surface, or its container expands before the reveal starts | Blocked until the transition is coordinated | +| An outgoing edge protrudes past the intended concealing field | Blocked until both directions preserve the boundary | +| A new selection animates, but the old selection snaps back or an unchanged neighbour shifts | Blocked until outgoing feedback and surrounding stability satisfy the guide | +| Rapid reversal continues smoothly to the latest state with stable neighbours | Accepted with applicable runtime evidence | | Animated thumbnail repeatedly processes a large original | Requires correction and relevant verification | | Prepared derivative preserves originals and rejects stale results | Accepted with applicable tests and interaction evidence | | Zero hitches recorded without actual interaction | Insufficient performance evidence; applicable verification remains blocked | diff --git a/AgentGuidelines/CHANGELOG.md b/AgentGuidelines/CHANGELOG.md index 1ece3b4..34d685f 100644 --- a/AgentGuidelines/CHANGELOG.md +++ b/AgentGuidelines/CHANGELOG.md @@ -2,6 +2,33 @@ All notable changes to this project are documented in this file. +## [0.0.51] - 2026-11-12 + +### Added + +- Added focused Design guides for user experience and animations, defining task continuity, justified automatic work and loading, discarded opportunistic refreshes, coordinated movement, concealment, graceful reversal, and stable neighbouring controls. +- Added framework-independent completion-audit coverage with observable acceptance scenarios, scoped runtime evidence, documentation-only walkthroughs, and concrete stopping rules for these experience requirements. + +### Changed + +- Linked the Design guides from SwiftUI, the consumer template, and the guideline catalog, retaining implementation and Reduce Motion policy in the SwiftUI guide. + +## [0.0.50] - 2026-11-10 + +### Changed + +- Required SwiftUI implementations for SwiftUI application UI, permitting UIKit/AppKit controllers, representables, hosting, or other bridges only for a demonstrated missing SwiftUI capability with prior owner approval and a durable, narrowly scoped exception. +- Added a mandatory completion-audit gate that traces interoperability through wrappers and dependencies, verifies SwiftUI alternatives and exception evidence, and rejects convenience or transition-style fallbacks that SwiftUI can implement. +- Added validator and mutation-test coverage protecting the SwiftUI-first policy and audit gate from removal or drift. + +## [0.0.49] - 2026-11-09 + +### Changed + +- Expanded task-based discovery of current Xcode skills for SwiftUI, resizability, App Intents, document-based applications, test modernization, and profiling while retaining deployment-aware, scoped adoption. +- Clarified SwiftUI observation dependencies, inexpensive stable collection identifiers, and constant row structure in lazy containers without introducing parallel Redux state ownership. +- Clarified Swift Testing's per-test suite lifecycle, cleanup requirements, and confirmation event timing. + ## [0.0.48] - 2026-11-06 ### Changed diff --git a/AgentGuidelines/Guidelines/Design/Animations.md b/AgentGuidelines/Guidelines/Design/Animations.md new file mode 100644 index 0000000..f7856e0 --- /dev/null +++ b/AgentGuidelines/Guidelines/Design/Animations.md @@ -0,0 +1,47 @@ +# Animations + +Motion should make a change understandable and an interaction feel continuous. Apply these experience requirements to app and game interfaces regardless of implementation framework. Use [User Experience](UX.md) to decide whether a change should interrupt the user and [SwiftUI animation](../Swift/SwiftUI.md#animation) for implementation policy. + +These are ThatFactory quality requirements informed by Apple's [motion guidance](https://developer.apple.com/design/human-interface-guidelines/motion). They describe observable behavior without prescribing a particular layout technique, animation curve, or duration. + +## Move a visual unit together + +- When a surface slides, moves, or resizes as one object, its title, body, icons, background, border, and other attached decoration must remain visually attached throughout the transition. A button's label must not arrive ahead of its background or continue travelling after the button settles. +- Coordinate the surrounding layout with the content it reveals or hides. A container that grows to reveal a button should resize as the button enters; avoid expanding an empty area first and then starting a separate entrance animation. Apply the same continuity when content disappears. +- Preserve the intended visual relationship throughout intermediate frames, including when motion reverses. Matching only the start and end states is insufficient. +- Use staggered or independently moving elements only for an explicit interaction or communication purpose. Document that purpose in the consumer's design guidance; accidental differences in timing are defects, not choreography. + +## Respect concealment and boundaries + +- When content appears to move from behind another surface or back into a concealed region, preserve that depth relationship for its entire path. No unintended edge, stroke, text, or background may protrude beyond the concealing surface or intended reveal area. +- Check both entrance and exit, including partial visibility and rapid reversal. For example, a button sliding away beneath a field must not leave its upper outline visible above the field. +- Keep intentional shadows, focus treatment, and readable content intact. Fix the particular reveal or concealment boundary without indiscriminately cutting off valid decoration or neighbouring content. + +## Reverse and interrupt gracefully + +- Give the return to an earlier state the same care as the initial change. If selection smoothly introduces a checkmark or changes color, font weight, or width, deselection must remove that feedback smoothly too. Do not animate the new choice while abruptly resetting the previous one. +- For a reversible slide reveal, return content toward the concealed origin it came from. A different exit path needs an explicit interaction purpose; do not change direction accidentally between entrance and exit. +- Coordinate all visible attributes that belong to that state change. A fading checkmark does not compensate for a snapping width, background, or label position. +- If input changes before motion finishes, continue smoothly from the currently displayed state toward the latest state. Do not jump back to a starting pose, play stale queued transitions, or force the user to wait for an obsolete animation. +- A graceful reversal need not literally replay identical frames or use identical timing. Preserve the spatial relationship and continuity while keeping the response prompt. Intentional immediate feedback remains valid when it serves the interaction; record the reason instead of leaving an unexplained snap. +- Keep actions and functional state responsive throughout motion, following the framework's implementation guidance. Animation must not delay selection, cancellation, or another valid action. + +## Keep unaffected surroundings stable + +- A local state change must not make unchanged neighbouring controls or labels jump or drift. For example, selecting one option must not nudge an unselected option's label sideways as a checkmark appears elsewhere. +- When a change legitimately requires surrounding layout to move, make that reflow coherent with the initiating change. Distinguish intended reflow from incidental jitter; do not freeze all layout or compromise adaptation to longer text and different content sizes to hide a defect. +- Check the outgoing element, incoming element, and unchanged neighbours together. A polished animation on the selected control alone does not establish that the interaction is polished. + +## Acceptance scenarios + +Observe the actual interaction at normal speed, then use recordings and intermediate-frame inspection to diagnose suspected sequencing, separation, or boundary defects. Record the platform/OS, app revision, scenario, actions, and result. A source-code animation modifier, successful build, static screenshot, or settled-state comparison does not prove correct motion. + +| Scenario | Required outcome | +| --- | --- | +| Reveal and hide a compound control | Attached content travels as one unit; required container resizing is coordinated | +| Move content behind a field, card, or other surface | No unintended edge or content leaks outside the concealment boundary in either direction | +| Select one option, then another | Both incoming and outgoing feedback transition smoothly; unchanged neighbours stay stable | +| Type and delete rapidly or reverse selection before motion finishes | Motion stays continuous, follows the latest state, and settles correctly without stale playback | +| Repeat with relevant longer labels and supported content sizes | Composition, concealment, and necessary reflow remain coherent | + +Apply the existing [Reduce Motion policy](../Swift/SwiftUI.md#reduce-motion) to affected motion; preserve the same information and task outcome with the appropriate adaptation. Missing applicable interaction evidence or an unresolved violation above prevents [audit completion](../../.agents/skills/agent-guidelines-audit/SKILL.md#audit-animation-and-image-rendering). Documentation-only changes use scenario walkthroughs, without claiming consumer runtime verification. diff --git a/AgentGuidelines/Guidelines/Design/UX.md b/AgentGuidelines/Guidelines/Design/UX.md new file mode 100644 index 0000000..e568af7 --- /dev/null +++ b/AgentGuidelines/Guidelines/Design/UX.md @@ -0,0 +1,42 @@ +# User Experience + +Preserve the user's intent, work, and sense of place. Automatic work must serve a current need without making the user manage the application's housekeeping. Apply this guide to app and game interfaces regardless of implementation framework; use [Animations](Animations.md) for motion quality and [SwiftUI](../Swift/SwiftUI.md) for implementation policy. + +These are ThatFactory experience requirements, informed by Apple's [launching](https://developer.apple.com/design/human-interface-guidelines/launching) and [loading](https://developer.apple.com/design/human-interface-guidelines/loading) guidance. Product-specific freshness requirements and necessary interruptions belong in durable consumer documentation. + +## Preserve the current task + +- Returning from another app should resume the current task. Preserve the active editor or presentation, unsaved input, selection, navigation, and relevant scroll and focus context. A brief app switch to copy information is part of that task, not a request to start over. +- Foreground activation alone does not justify dismissing a flow, returning to a root screen, covering usable content with loading UI, or taking input focus. Retaining the draft underneath an unnecessary overlay still interrupts the user. +- Distinguish a temporary absence from initial loading, a new user request, and an actual change that invalidates access or makes continuing unsafe. Do not replay the startup experience on every activation. +- When interruption is necessary, limit it to the affected task, explain the reason and recovery path, and preserve recoverable work where safe. Genuine account changes, revoked access, and unsafe or invalid data must still be handled promptly; continuity never authorizes exposing another account's content or committing invalid work. + +## Perform automatic work for a current reason + +- Identify the trigger, the current need, and the user-visible effect of each automatic refresh or reload. A lifecycle callback is an opportunity to assess that need, not proof that a disruptive reload is required. +- Prefer quiet, nonblocking updates when they can preserve the current task and valid content. Do not replace usable content with a startup or full-screen loading state merely because a routine refresh is in progress. A background operation that unexpectedly replaces a draft, moves the user's location, or steals focus is still disruptive. +- For an opportunistic foreground refresh that would disturb an active task, skip that attempt when the user is busy. Do not queue it for replay when an editor, chooser, search, settings, or another flow closes. Finishing or cancelling a task is not, by itself, a new refresh request. +- Reassess at a new independent trigger, such as a later eligible foreground activation, an explicit refresh, or a relevant data change. A save or deletion can legitimately synchronize the mutation it just made; it does not justify replaying an unrelated skipped refresh. +- Defer required work only when it remains necessary for a concrete operation or documented freshness requirement. Record why it cannot be skipped, when it becomes eligible, how its need is rechecked, and what the user will experience. Do not invent deferred work merely to ensure that every lifecycle event eventually causes a reload. +- Reassess before showing loading UI or publishing a disruptive result if the user has started another task since the work began. An earlier idle state does not authorize interrupting a newly opened editor or presentation. + +## Make waiting proportionate and understandable + +- Show blocking loading UI only when the affected task cannot safely continue without the result. Keep unaffected content and actions available when possible, and make clear what is loading. +- Scope progress, failure, and retry to the operation that needs them. Do not turn a routine refresh failure into an unrelated modal interruption when the current task can continue safely. +- Preserve valid user context through completion and failure. Avoid surprise loading screens after dismissal, duplicate reloads for the same need, and artificial waits added only to make an animation or loading screen visible. + +## Acceptance scenarios + +Exercise the changed paths and directly affected flows. Record the platform/OS, app revision, initial state, trigger, actions, and observed result. Use runtime interaction for continuity and visible loading, with deterministic tests or event evidence where needed to distinguish a skipped request from a silently deferred one. Static screenshots cannot establish continuity across an interruption. + +| Scenario | Required outcome | +| --- | --- | +| Switch away with unsaved edits, then return | The editor and draft remain usable without an unnecessary overlay or navigation reset | +| Switch away while entering a value or choosing options, then return | Input, selection, presentation, and relevant focus context survive | +| Routine foreground refresh is skipped during a task; then save, cancel, or dismiss it | No catch-up refresh is caused solely by closing the flow; any mutation synchronization has its own reason | +| A later eligible activation or explicit refresh occurs | Freshness is reassessed for that new trigger; a valid refresh can proceed | +| An automatic refresh begins while idle; the user then opens an editor | Completion or loading UI does not displace the new task | +| Access is actually revoked or the active account changes | Unsafe access stops promptly, with an appropriate explanation and safe handling of recoverable work | + +An unnecessary interruption, an unjustified catch-up refresh, lost task context, or missing applicable evidence prevents [audit completion](../../.agents/skills/agent-guidelines-audit/SKILL.md#audit-user-experience). Documentation-only policy work uses scenario walkthroughs; it does not establish compliance in a consumer application. diff --git a/AgentGuidelines/Guidelines/Swift/SwiftUI.md b/AgentGuidelines/Guidelines/Swift/SwiftUI.md index 1c01cbf..17ced9d 100644 --- a/AgentGuidelines/Guidelines/Swift/SwiftUI.md +++ b/AgentGuidelines/Guidelines/Swift/SwiftUI.md @@ -2,6 +2,18 @@ Use official Apple documentation and Xcode's current SwiftUI skills for API-specific behavior. This guide captures stable project policy rather than reproducing the current SDK's API catalog. +Apply [User Experience](../Design/UX.md) when changing task continuity, lifecycle-driven UI, automatic refreshes, or loading behavior. It defines when work and interruptions are warranted independently of the implementation framework. + +## SwiftUI-first implementation + +Implement a SwiftUI application's UI with SwiftUI. Do not introduce or expand UIKit or AppKit UI code, view controllers, `UIViewRepresentable`, `UIViewControllerRepresentable`, `NSViewRepresentable`, `NSViewControllerRepresentable`, `UIHostingController`, `NSHostingController`, or equivalent bridges unless the required behavior cannot be implemented with public SwiftUI APIs on the supported deployment targets. A UIKit implementation being Apple-native does not satisfy this SwiftUI-first requirement. + +Before considering interoperability, evaluate SwiftUI's controls, presentation modifiers, state, layout, transitions, animations, and materials, including compositions of those APIs. Verify the relevant current Apple/Xcode documentation and use a focused SwiftUI reproduction when behavior is uncertain. Failure of a first attempt, convenience, familiarity with UIKit, a desired transition style, or a wrapper with a SwiftUI-facing name is not evidence of a missing SwiftUI capability. If SwiftUI can implement the behavior, use it; do not request a convenience exception. + +Only a demonstrated SwiftUI capability gap can justify interoperability. Before implementing that fallback, obtain explicit repository-owner approval and record a durable consumer exception identifying the required behavior, supported targets, evaluated SwiftUI alternatives, documentation or reproducible evidence that those alternatives cannot meet the requirement, approved boundary, lifecycle and state ownership, validation, and a condition for revisiting the fallback. Approval alone does not replace capability-gap evidence. Keep any approved bridge limited to the missing capability rather than moving unrelated SwiftUI presentation or application state into a parallel controller hierarchy. + +Do not bypass this rule through controller introspection, a reusable component, or a dependency that hides the same UIKit/AppKit implementation. Inspect the actual UI responsibility, not just the import or wrapper name. The [native-component policy](#native-components-and-presentation) remains an additional requirement; calling a UIKit presenter native does not waive this rule. Unjustified interoperability blocks completion and the [completion audit](../../.agents/skills/agent-guidelines-audit/SKILL.md#audit-swiftui-first-implementation). + ## View structure - Put SwiftUI dynamic properties such as `@Environment`, `@Query`, `@State`, and `@Binding` before ordinary stored `let` and `var` properties. Keep injected environment dependencies before locally owned state when both are present. @@ -21,6 +33,7 @@ Use official Apple documentation and Xcode's current SwiftUI skills for API-spec - In non-Redux designs, prefer `@Observable` to `ObservableObject` for new shared reference models when platform support allows it. - In Redux applications, keep durable app and domain state in Redux. Do not introduce an observable view model as a parallel source of truth. - Make observable stored-property types `Equatable` when equality matches their semantics, allowing redundant assignments to avoid unnecessary invalidation. +- Account for observation granularity: reading a field of a stored value-type property or an element of a stored collection can establish a dependency on the whole property. A computed lookup still tracks the properties it reads. When broad invalidation matters, expose narrow state slices or maintain derived values at the existing state owner; preserve Redux ownership rather than adding a parallel observable model or an unsynchronized cache. Reading several already-narrow properties does not itself require splitting a model. - Isolate side effects in `.task`, `.onChange`, actions, or explicit async functions rather than hiding them in rendering logic. - Use the current `.onChange(of:)` form and read the updated captured value when the previous value is unnecessary. - Avoid closure-based bindings when a writable key-path binding expresses the same relationship. @@ -31,11 +44,15 @@ With SDKs where `@State` is a macro, do not give a state property a declaration - Give `ForEach`, `List`, `Table`, and similar data-driven views stable, unique element identity. - Prefer meaningful `Identifiable` conformance when the model has natural identity. +- Keep identifiers cheap to hash and compare. Do not use an entire large value as its identifier merely because it conforms to `Hashable`; preserve that conformance for other uses and select a small stable key for collection identity. - Do not use collection indices, offsets, or transient UUIDs as identity for mutable collections. - Do not sort, filter, or map large collections inline inside a frequently evaluated view body. Prepare the collection before rendering. - Use a dedicated row `View` for meaningful rows and pass it narrow inputs. +- In lazy containers such as `List` and `LazyVStack`, keep a constant number of top-level views per element. Use an appropriate single-root container around branching row content when needed; `Group` does not provide that container. If an element should have no row, filter the prepared collection instead of producing a zero-view row or adding an empty container. - Avoid `AnyView` in collection rows. +Consult Apple's [model-data guidance](https://developer.apple.com/documentation/swiftui/managing-model-data-in-your-app) for observation dependencies and [`ForEach` documentation](https://developer.apple.com/documentation/swiftui/foreach) for lazy-container row structure. Use the current Xcode SwiftUI skill for detailed diagnostics and SDK-specific behavior. + ## Modifiers and environment - Preserve stable view identity. Prefer modifiers whose values change over conditionally adding and removing modifier branches. @@ -59,7 +76,7 @@ With SDKs where `@State` is a macro, do not give a state property a declaration ## Native components and presentation -- Prefer native SwiftUI or platform controls and presentation APIs whenever they express the supported interaction. Evaluate sheets, alerts, confirmation dialogs, navigation, menus, pickers, popovers, and similar components before implementing an equivalent. Consult official Apple/Xcode documentation for behavior and availability on the current deployment target, following [documentation lookup](../Xcode/MCP.md#documentation-lookup). +- Use native SwiftUI controls and presentation APIs in SwiftUI applications whenever they express the supported interaction. Evaluate sheets, alerts, confirmation dialogs, navigation, menus, pickers, popovers, and similar components before implementing an equivalent. UIKit/AppKit alternatives must first satisfy the [SwiftUI-first requirement](#swiftui-first-implementation). Consult official Apple/Xcode documentation for behavior and availability on the current deployment target, following [documentation lookup](../Xcode/MCP.md#documentation-lookup). - Keep branded content and styling inside native components. Custom fonts, button styles, and content inside a native sheet are compatible with this policy when the system retains presentation and dismissal ownership. - Do not substitute a sheet-shaped `ZStack`, offset animation, or custom scrim for a suitable native sheet API. The same rule applies to other simulated system components, including custom discard dialogs. Pixel fidelity to a static design and preserving mounted state are insufficient reasons to replace native presentation behavior; a mockup is not approval for an exception. - Use a custom equivalent only for an actual native capability gap verified against the supported platform and deployment target. Before implementation, obtain explicit repository-owner approval and record a durable exception in consumer documentation: the required interaction, evaluated native alternatives, concrete missing capability and documentation or reproducible evidence, approved scope, lifecycle ownership, compensating validation, and revisit condition. Do not invent a capability gap or infer approval from existing custom code. An unapproved or undocumented replacement blocks completion. @@ -103,6 +120,8 @@ Use these decisions when auditing an implementation: ## Animation +Apply [Animations](../Design/Animations.md) for coordinated movement, concealment boundaries, graceful reversal, and stable surroundings. Those observable requirements complement the implementation rules below. + - Use native SwiftUI animation to make apps fluid rather than static. Apply it purposefully to buttons, transitions, interactions, selection, colors, and other visible state changes that benefit from feedback; do not animate every update or add motion for its own sake. - Prefer the default SwiftUI animation, using `withAnimation { ... }` or `.animation(.default, value: ...)`, unless the task prompt explicitly requests a specific animation. Prefer system-provided transitions and SF Symbol effects when they fit the interaction instead of recreating them with custom timing, curves, or rendering. - Reusable custom-styled controls own their basic visual transitions. Animate enabled/disabled appearance smoothly by default in both directions, without screen-level opt-in. A native `Button` preserves interaction semantics, but does not define transitions for every custom foreground, background, or shadow. Preserve system-owned feedback instead of layering duplicate animation over it. diff --git a/AgentGuidelines/Guidelines/Testing/UnitTesting.md b/AgentGuidelines/Guidelines/Testing/UnitTesting.md index cc14fb3..a96efa8 100644 --- a/AgentGuidelines/Guidelines/Testing/UnitTesting.md +++ b/AgentGuidelines/Guidelines/Testing/UnitTesting.md @@ -11,7 +11,8 @@ - Organize test intent with `// Given`, `// When`, and `// Then` where the phases are meaningful. - Prefer `struct` suites. Use a reference type only when lifecycle or identity requires it. -- Use suite initialization and `deinit` only for genuine shared setup and cleanup. +- Initialize per-test fixtures in the suite initializer when setup is needed. Swift Testing creates a fresh suite instance for each instance test; initialization is not once-per-suite setup shared across tests. +- Use a `final class` or actor suite when per-instance cleanup requires `deinit`; a `struct` suite cannot provide a deinitializer. Do not use that cleanup as a once-per-suite teardown mechanism. - Keep each test focused on one behavior and name it in domain language. - Mirror production physical folders under the test target. - Put reusable mocks and fixtures under the test target's `Mocks/` folder. @@ -25,6 +26,7 @@ - Use `#require` for prerequisites whose failure must stop the current test. - Prefer exact thrown-error expectations when the particular error is part of the contract. - Use confirmation APIs for callback or delegate behavior rather than hand-built counters and arbitrary delays. +- A confirmation checks its expected event count when its closure returns; it does not wait for future callbacks. Await the operation that delivers the event inside the closure, or use an appropriate async bridge for a completion-handler API. Do not mechanically replace an XCTest wait with a confirmation that returns before the event can occur. - Record known failures with Swift Testing's known-issue support instead of silently disabling coverage. ## Concurrency @@ -52,3 +54,5 @@ Follow [Xcode MCP](../Xcode/MCP.md) for build and runtime verification. Follow [Networking](../Networking.md#ownership-and-validation) for networking test boundaries and required evidence. + +Consult Apple's [XCTest migration guidance](https://developer.apple.com/documentation/testing/migratingfromxctest) for suite lifecycle and asynchronous confirmations, and Xcode's current test-modernization skill for detailed migration patterns. diff --git a/AgentGuidelines/Guidelines/Xcode/MCP.md b/AgentGuidelines/Guidelines/Xcode/MCP.md index 5a852e4..0dfee84 100644 --- a/AgentGuidelines/Guidelines/Xcode/MCP.md +++ b/AgentGuidelines/Guidelines/Xcode/MCP.md @@ -19,6 +19,21 @@ Discover the tools exposed by the active Xcode server. Tool prefixes and exact n - Use Xcode-provided skills for specialized current workflows such as SwiftUI modernization, localization, security auditing, device interaction, and C bounds safety. - Distill durable project policy into local documentation; do not copy an exported Apple skill into a repository. +### Specialized skill selection + +Discover the installed skills and read the references relevant to the task before applying SDK-specific changes. These names are discovery hints from current Xcode exports, not guarantees that a host exposes a skill or tool with that exact name. If a relevant skill is unavailable, use current official Apple documentation and report any unresolved limitation. + +| Task | Relevant Xcode skill | +| --- | --- | +| SwiftUI structure, data flow, identity, or modernization | `swiftui-specialist`; `swiftui-whats-new-27` for SDK 27 source and API changes | +| Window resizing, scene lifecycle, local geometry, or changing safe areas | `app-resizability` | +| App Intents, entities, queries, or Shortcuts | `app-intents-specialist`; `app-intents-whats-new-27` for release-specific adoption | +| Document-based SwiftUI open, edit, save, export, or migration | `building-document-based-swiftui-applications` | +| XCTest migration or Swift Testing modernization | `modernize-tests` | +| Profiling, trace inspection, or hang diagnosis | `xctrace` | + +Keep adoption scoped to the requested work and deployment targets. For profiling, inspect the selected toolchain's command help before relying on `xctrace` subcommands or flags, and capture the workload being diagnosed; an idle trace is not performance evidence. A newer exported skill does not authorize a whole-repository migration, higher deployment targets, or changes to consumer exceptions. + ## Project operations - Prefer Xcode project-aware file, target, build-setting, issue, build, test, preview, and documentation tools when available. diff --git a/AgentGuidelines/README.md b/AgentGuidelines/README.md index bea794f..d175071 100644 --- a/AgentGuidelines/README.md +++ b/AgentGuidelines/README.md @@ -61,6 +61,7 @@ The subtree does not automatically import every guide into an agent's context. A ## Guideline catalog - [Agent workflow and tool execution](Guidelines/AgentWorkflow.md) +- [Animations](Guidelines/Design/Animations.md) - [App Store metadata](Guidelines/AppStore.md) - [CI/CD](Guidelines/CICD.md) - [Codex review policy](ReviewPolicy/README.md) @@ -80,11 +81,12 @@ The subtree does not automatically import every guide into an agent's context. A - [Swift style](Guidelines/Swift/SwiftStyle.md) - [SwiftUI](Guidelines/Swift/SwiftUI.md) - [Unit and integration testing](Guidelines/Testing/UnitTesting.md) +- [User experience](Guidelines/Design/UX.md) - [Xcode MCP and visual verification](Guidelines/Xcode/MCP.md) - [Xcode project settings](Guidelines/Xcode/ProjectSettings.md) - [Xcode security audits](Guidelines/Xcode/Security.md) -Only reference the guides that apply. Agent workflow normally applies to both applications and packages. A UI-agnostic package normally also uses Swift, style, testing, documentation, logging, packages, CI/CD, and Xcode guidance, but not Redux or SwiftUI guidance. +Only reference the guides that apply. Agent workflow normally applies to both applications and packages. App and game interface work uses the Design guides alongside the relevant implementation guide. A UI-agnostic package normally also uses Swift, style, testing, documentation, logging, packages, CI/CD, and Xcode guidance, but not Design, Redux, or SwiftUI guidance. ## Add to a consumer @@ -94,7 +96,7 @@ From the consumer repository root, install a tagged release: git subtree add \ --prefix=AgentGuidelines \ https://github.com/thatfactory/agent-guidelines.git \ - 0.0.48 \ + 0.0.51 \ --squash ``` @@ -156,7 +158,7 @@ Review the target release's changelog, then pull it deliberately: git subtree pull \ --prefix=AgentGuidelines \ https://github.com/thatfactory/agent-guidelines.git \ - 0.0.48 \ + 0.0.51 \ --squash ``` diff --git a/AgentGuidelines/Scripts/validate_guidelines.swift b/AgentGuidelines/Scripts/validate_guidelines.swift index 4550257..953b3e8 100755 --- a/AgentGuidelines/Scripts/validate_guidelines.swift +++ b/AgentGuidelines/Scripts/validate_guidelines.swift @@ -720,12 +720,58 @@ func validateNetworkingPolicy(_ errors: inout [String]) { } } +/// Protects the SwiftUI-first threshold and its mandatory completion-audit gate. +func validateSwiftUIFirstPolicy(_ errors: inout [String]) { + let requirements: [(URL, [String])] = [ + ( + swiftUIGuideline, + [ + "## SwiftUI-first implementation", + "Implement a SwiftUI application's UI with SwiftUI", + "`UIViewRepresentable`, `UIViewControllerRepresentable`", + "`NSViewRepresentable`, `NSViewControllerRepresentable`", + "`UIHostingController`, `NSHostingController`", + "unless the required behavior cannot be implemented with public SwiftUI APIs", + "A UIKit implementation being Apple-native does not satisfy this SwiftUI-first requirement", + "including compositions of those APIs", + "If SwiftUI can implement the behavior, use it; do not request a convenience exception", + "obtain explicit repository-owner approval and record a durable consumer exception", + "Approval alone does not replace capability-gap evidence", + "Do not bypass this rule through controller introspection", + "Unjustified interoperability blocks completion", + ] + ), + ( + auditSkill, + [ + "Perform the mandatory [SwiftUI-first implementation check]", + "## Audit SwiftUI-first implementation", + "Guidelines/Swift/SwiftUI.md#swiftui-first-implementation", + "Follow wrappers and relevant dependency calls to their implementation", + "Include directly affected existing bridges rather than grandfathering them", + "Require current documentation or reproducible evidence that SwiftUI cannot meet the requirement", + "When SwiftUI can implement the behavior, require the in-scope implementation to use SwiftUI", + "UIKit/AppKit interoperability without a demonstrated SwiftUI capability gap blocks audit completion", + "verify explicit repository-owner approval before implementation", + "Approval alone does not replace capability-gap evidence", + "Keep approved interoperability limited to the missing capability", + ] + ), + ] + for (url, fragments) in requirements { + guard let contents = readText(url, errors: &errors) else { continue } + for fragment in fragments where !contents.contains(fragment) { + errors.append("\(relativePath(url)): missing SwiftUI-first requirement '\(fragment)'") + } + } +} + /// Protects the native-component decision, ownership, and runtime-evidence policy. func validateNativeComponentPolicy(_ errors: inout [String]) { guard let contents = readText(swiftUIGuideline, errors: &errors) else { return } let required = [ "## Native components and presentation", - "Prefer native SwiftUI or platform controls and presentation APIs", + "Use native SwiftUI controls and presentation APIs in SwiftUI applications", "sheets, alerts, confirmation dialogs, navigation, menus, pickers, popovers", "Custom fonts, button styles, and content inside a native sheet are compatible", "Do not substitute a sheet-shaped `ZStack`, offset animation, or custom scrim", @@ -1121,6 +1167,7 @@ func main() -> Int32 { validatePackageCompilerSettingsGuideline(&errors) validateExternalDependencyPolicy(&errors) validateNetworkingPolicy(&errors) + validateSwiftUIFirstPolicy(&errors) validateNativeComponentPolicy(&errors) validateInteractionRenderingPolicy(&errors) validateCodexReviewEvidence(&errors) diff --git a/AgentGuidelines/Templates/AGENTS.md b/AgentGuidelines/Templates/AGENTS.md index 0b6d6a7..3aeede3 100644 --- a/AgentGuidelines/Templates/AGENTS.md +++ b/AgentGuidelines/Templates/AGENTS.md @@ -30,6 +30,8 @@ Read only the guides relevant to the task: For an application that uses Redux, also read [Redux architecture](AgentGuidelines/Guidelines/Architecture/Redux.md). +For app and game interface work, also read [User experience](AgentGuidelines/Guidelines/Design/UX.md) when changing task continuity, automatic work, or loading, and [Animations](AgentGuidelines/Guidelines/Design/Animations.md) when changing motion. Apply these experience requirements alongside the framework-specific implementation guide. + For Codex pull-request review, use the linked review evidence rules. If authoritative repository-specific evidence establishes that automatic review is enabled, apply its current-head gate. If the executing agent cannot establish the setting, record it as `unknown`; this template does not establish that automatic review is configured. Keep the following observability contract in the consumer repository's root `AGENTS.md` so implementation agents treat runtime diagnostics as part of lifecycle work. Copy it unchanged and update it when the marker version changes in this template. diff --git a/AgentGuidelines/Tests/run_tests.swift b/AgentGuidelines/Tests/run_tests.swift index 5255035..6ee2007 100755 --- a/AgentGuidelines/Tests/run_tests.swift +++ b/AgentGuidelines/Tests/run_tests.swift @@ -306,6 +306,51 @@ let tests: [(String, () throws -> Void)] = [ } } ), + ( + "SwiftUI-first validator rejects missing policy and audit safeguards", + { + let mutations: [(String, [String])] = [ + ( + "Guidelines/Swift/SwiftUI.md", + [ + "unless the required behavior cannot be implemented with public SwiftUI APIs", + "A UIKit implementation being Apple-native does not satisfy this SwiftUI-first requirement", + "If SwiftUI can implement the behavior, use it; do not request a convenience exception", + "obtain explicit repository-owner approval and record a durable consumer exception", + "Approval alone does not replace capability-gap evidence", + "Do not bypass this rule through controller introspection", + ] + ), + ( + ".agents/skills/agent-guidelines-audit/SKILL.md", + [ + "Perform the mandatory [SwiftUI-first implementation check]", + "Follow wrappers and relevant dependency calls to their implementation", + "Require current documentation or reproducible evidence that SwiftUI cannot meet the requirement", + "When SwiftUI can implement the behavior, require the in-scope implementation to use SwiftUI", + "UIKit/AppKit interoperability without a demonstrated SwiftUI capability gap blocks audit completion", + "verify explicit repository-owner approval before implementation", + ] + ), + ] + try withTemporaryDirectory { temporary in + let fixture = temporary.appendingPathComponent("repository") + try copyRepositoryFixture(to: fixture) + for (path, fragments) in mutations { + let file = fixture.appendingPathComponent(path) + let contents = try String(contentsOf: file, encoding: .utf8) + for fragment in fragments { + try require(contents.contains(fragment), "missing test fixture text: \(fragment)") + try write(contents.replacingOccurrences(of: fragment, with: "REMOVED"), to: file) + let result = try run([fixture.appendingPathComponent("Scripts/validate_guidelines.swift").path]) + try require(!result.succeeded, "SwiftUI-first mutation unexpectedly passed: \(fragment)") + try require(result.output.contains("missing SwiftUI-first requirement"), result.output) + try write(contents, to: file) + } + } + } + } + ), ( "native-component validator rejects policy and decision drift", { diff --git a/AgentGuidelines/VERSION b/AgentGuidelines/VERSION index a24809a..c4132bc 100644 --- a/AgentGuidelines/VERSION +++ b/AgentGuidelines/VERSION @@ -1 +1 @@ -0.0.48 +0.0.51 diff --git a/Sources/CloudSaveKit/CloudSaveAccountEvent.swift b/Sources/CloudSaveKit/CloudSaveAccountEvent.swift index d9d728e..2fb0b19 100644 --- a/Sources/CloudSaveKit/CloudSaveAccountEvent.swift +++ b/Sources/CloudSaveKit/CloudSaveAccountEvent.swift @@ -2,7 +2,7 @@ import Foundation /// Account-bound cloud work is fenced before invalidation is published to the host. public enum CloudSaveAccountEvent: Equatable, Sendable { - /// Hide old account content before awaiting local or cloud teardown. + /// Revoke old cloud authority immediately; local visibility follows the host's authorization policy. case invalidated /// A revalidation completed; persisted account strings alone do not establish trust. case resolved(CloudSaveAccountSnapshot) diff --git a/Sources/CloudSaveKit/CloudSaveKit.docc/PrivateCollections.md b/Sources/CloudSaveKit/CloudSaveKit.docc/PrivateCollections.md index 1ff040a..6736c12 100644 --- a/Sources/CloudSaveKit/CloudSaveKit.docc/PrivateCollections.md +++ b/Sources/CloudSaveKit/CloudSaveKit.docc/PrivateCollections.md @@ -10,9 +10,9 @@ The configurable engine and sharing APIs remain supported. Personal sessions opt ## Observe and verify the account -Create one coordinator for a container and consume its ``CloudSavePrivateCoordinator/accountEvents`` stream before opening local persistence. The coordinator registers `CKAccountChanged` observation during initialization. ``CloudSavePrivateCoordinator/startMonitoring()`` starts its consumer idempotently; ``CloudSavePrivateCoordinator/refreshAccount()`` also starts monitoring. +Create one coordinator for a container and consume its ``CloudSavePrivateCoordinator/accountEvents`` stream before authorizing account-bound cloud work. The coordinator registers `CKAccountChanged` observation during initialization. ``CloudSavePrivateCoordinator/startMonitoring()`` starts its consumer idempotently; ``CloudSavePrivateCoordinator/refreshAccount()`` also starts monitoring. -An `.invalidated` event means the host must immediately clear visible account content, navigation, drafts, game state, images, and operation status before awaiting teardown. The coordinator fences old cloud work before emitting the event. It then resolves availability and the current opaque account record name. Notifications are revalidation triggers, including notifications caused by another Apple TV profile; they are not proof of an account identity. Forward foreground activation by calling `refreshAccount()` rather than adding another raw CloudKit observer. +An `.invalidated` event revokes old cloud authority immediately. The coordinator fences old cloud work before emitting the event, then resolves availability and the current opaque account record name. Local visibility is a separate host policy: a host whose only authorization is the current verified account must immediately hide account content and fence navigation, drafts, games, images, and operation status before awaiting teardown. A host with explicit independent device authorization may retain its locally authorized collection and presentation while verification runs. It must still reject retired cloud operations and isolate actual owner changes. Notifications are revalidation triggers, including notifications caused by another Apple TV profile; they are not proof of an account identity. Forward foreground activation by calling `refreshAccount()` rather than adding another raw CloudKit observer. Only `.verified(account)` supplies a ``CloudSaveVerifiedAccount`` token. Its initializer is internal and it contains coordinator/generation provenance. A stored account string is useful as a local namespace key but cannot recreate verification. Refreshes coalesce while in flight; a later account notification supersedes a suspended query immediately. Every fresh reconciliation invalidates previous tokens and sessions, even if the resolved account is the same. @@ -72,7 +72,7 @@ try await session.fetchNow() // Now a newly initialized local projection may truthfully be reported as empty. ``` -`start()` restores the durable ledger; it is not a remote fetch barrier. `fetchNow()` preserves the existing engine's freshness and host-apply guarantees. A failed initial fetch must remain a recovery state instead of reporting a new collection as empty. +`start()` restores the durable ledger; it is not a remote fetch barrier. `fetchNow()` preserves the existing engine's freshness and host-apply guarantees. A failed initial fetch cannot establish that the remote collection is empty or synchronized. Independently authorized local data may remain ready while that remote state is unknown. When local pending work needs reconciliation with an existing remote collection, create the session with `automaticallySync: false`, start it, fetch and durably apply remote state, validate the host's reconciliation barrier, and only then send. The host's local readiness and ownership claims do not substitute for this barrier. The supplied client must permanently reference the original local store. Personal sessions never invoke the client's mutable-account rebinding callback. A matching sign-in may restore its ledger; a sign-out, switch, or mismatched sign-in invalidates the session first. Known-zone deletion and `zoneNotFound` are integrity failures: no automatic zone save, local zone-deletion callback, or speculative manifest replacement is permitted. The local mutation ledger must never contain the bootstrap manifest itself. @@ -82,7 +82,9 @@ The session retains the bootstrap's pure decoder and canonical identity. Incomin ## Offline trust and temporary availability -An ordinary network failure can leave an already verified same-account local collection usable. On cold launch, first establish the current identity through the coordinator; a matching trusted binding may then support an initialized offline cache if remote bootstrap fails with a transport outage. If current identity cannot be verified, hide caches and retain their bytes. A last-used account string, or tvOS's per-profile storage alone, is insufficient to prove that the Apple Account within that context has not changed. +An ordinary network failure can leave an already verified same-account local collection usable. For an account-fenced cache, including an Apple TV host without independent local authorization, cold launch first establishes the current identity through the coordinator; a matching trusted binding may then support an initialized offline cache if remote bootstrap fails with a transport outage. If identity cannot be verified, hide that cache and retain its bytes. A last-used account string, or tvOS's per-profile storage alone, is insufficient to prove that the Apple Account within that context has not changed. + +A host may instead explicitly authorize device-local access before current cloud verification. That policy is owned by the host, not granted by a stored account name or this package. Keep local identity, readiness, and presentation leases separate from cloud token generations. Edits to a previously claimed collection remain owned by its original account, even while current identity is unresolved; never relabel them as guest data or enqueue them into another account's session. Confirmed sign-out and verified owner changes require the host's defined isolated collection selection. An unbound local collection requires a durable host-owned claim and reconciliation before cloud exposure. None of these policies permits opening an unverified cloud session or transplanting a checkpoint across account, canonical collection, or zone provenance. Temporary account unavailability preserves local data and committed ledger entries, while fencing new CloudKit operations and enqueues. A private session retires its engine when that failure arrives through explicit operations or automatic engine events. `suspend()` and `invalidate()` are terminal for that handle. After account availability is verified again, bootstrap and create a new session from the latest durable checkpoint; there is no mutable resume or account-rebinding operation.