Package dev.turboism.sdk.appearance

Interface AppearanceService

public interface AppearanceService
Plugin-scoped Preview service for a single runtime-owned semantic appearance override.

Runtime policy, not plugins, accesses the native UI. Results are asynchronous to preserve the service boundary, but callers must not infer a particular completion thread. A granted turboism.ui.appearance.modify permission authorizes requests; provider availability, revision arbitration, ownership, safe mode, and host-version support remain independent.

  • Method Details

    • current

      CompletionStage<AppearanceStatus> current()
      Obtains the current semantic appearance status.
      Returns:
      a stage completing with a non-null status, including unavailable or unsupported state

    • apply

      CompletionStage<AppearanceApplyResult> apply(AppearanceRequest request)
      Attempts to apply a temporary appearance owned by this plugin generation.

      Use the status revision for AppearanceRequest.expectedRevision(). An accepted owner must later call restoreOwnedAppearance() or rely on plugin/runtime cleanup.

      Parameters:
      request - non-null optimistic-concurrency request
      Returns:
      a stage completing with an applied, no-change, rejected, unavailable, or failure-and-restoration result
      Throws:
      NullPointerException - if request is null
      CubismPermissionException - if the plugin lacks the appearance-modification permission

    • restoreOwnedAppearance

      CompletionStage<AppearanceRestoreResult> restoreOwnedAppearance()
      Restores the baseline captured when this plugin generation acquired the active override.

      A plugin cannot restore another plugin's override. This is safe to call during disable; AppearanceRestoreResult.Outcome.NO_OWNED_OVERRIDE means there is nothing owned to restore.

      Returns:
      a stage completing with the restore disposition and current status
      Throws:
      CubismPermissionException - if the plugin lacks the appearance-modification permission

    • unavailable

      static AppearanceService unavailable()
      Returns a fail-closed service for contexts that do not expose an appearance provider.
      Returns:
      a service whose queries report unavailable and whose operations return typed unavailable results