rork-xcode 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -204,20 +204,26 @@ declare class PbxprojBuildError extends Error {
  */
 declare const Isa: {
   readonly aggregateTarget: "PBXAggregateTarget";
+  readonly appleScriptBuildPhase: "PBXAppleScriptBuildPhase";
   readonly buildFile: "PBXBuildFile";
   readonly buildRule: "PBXBuildRule";
+  readonly buildStyle: "PBXBuildStyle";
   readonly containerItemProxy: "PBXContainerItemProxy";
   readonly copyFilesBuildPhase: "PBXCopyFilesBuildPhase";
   readonly fileReference: "PBXFileReference";
   readonly fileSystemSynchronizedBuildFileExceptionSet: "PBXFileSystemSynchronizedBuildFileExceptionSet";
+  readonly fileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet: "PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet";
   readonly fileSystemSynchronizedRootGroup: "PBXFileSystemSynchronizedRootGroup";
   readonly frameworksBuildPhase: "PBXFrameworksBuildPhase";
   readonly group: "PBXGroup";
+  readonly headersBuildPhase: "PBXHeadersBuildPhase";
   readonly legacyTarget: "PBXLegacyTarget";
   readonly nativeTarget: "PBXNativeTarget";
   readonly project: "PBXProject";
   readonly referenceProxy: "PBXReferenceProxy";
   readonly resourcesBuildPhase: "PBXResourcesBuildPhase";
+  readonly rezBuildPhase: "PBXRezBuildPhase";
+  readonly shellScriptBuildPhase: "PBXShellScriptBuildPhase";
   readonly sourcesBuildPhase: "PBXSourcesBuildPhase";
   readonly targetDependency: "PBXTargetDependency";
   readonly variantGroup: "PBXVariantGroup";
@@ -228,6 +234,16 @@ declare const Isa: {
   readonly swiftPackageProductDependency: "XCSwiftPackageProductDependency";
   readonly versionGroup: "XCVersionGroup";
 };
+/**
+ * One of the `isa` names of the vocabulary, the union of the values of
+ * {@link Isa}.
+ */
+type IsaValue = (typeof Isa)[keyof typeof Isa];
+/**
+ * The `isa` names of the build phase kinds. The phase helpers on targets
+ * accept these, and the literal passed picks the phase class they return.
+ */
+type BuildPhaseIsa = typeof Isa.appleScriptBuildPhase | typeof Isa.copyFilesBuildPhase | typeof Isa.frameworksBuildPhase | typeof Isa.headersBuildPhase | typeof Isa.resourcesBuildPhase | typeof Isa.rezBuildPhase | typeof Isa.shellScriptBuildPhase | typeof Isa.sourcesBuildPhase;
 /**
  * Product type identifiers of the targets the model creates or reasons
  * about. Other product types pass through untouched.
@@ -405,21 +421,31 @@ interface ReferenceProxyProperties extends PbxprojObject {
   sourceTree?: string;
 }
 /**
- * Properties shared by the `PBX*BuildPhase` kinds. Copy-files and
- * shell-script phases carry the destination and script keys. The standard
- * phases leave them absent.
+ * Properties shared by every `PBX*BuildPhase` kind.
  */
 interface BuildPhaseProperties extends PbxprojObject {
   buildActionMask?: number;
+  files?: string[];
+  name?: string;
+  runOnlyForDeploymentPostprocessing?: number;
+}
+/**
+ * Properties of a `PBXCopyFilesBuildPhase`, which adds the destination
+ * the files are copied to.
+ */
+interface CopyFilesBuildPhaseProperties extends BuildPhaseProperties {
   dstPath?: string;
   dstSubfolderSpec?: number;
-  files?: string[];
+}
+/**
+ * Properties of a `PBXShellScriptBuildPhase`, which adds the script, its
+ * interpreter, and the declared inputs and outputs.
+ */
+interface ShellScriptBuildPhaseProperties extends BuildPhaseProperties {
   inputFileListPaths?: string[];
   inputPaths?: string[];
-  name?: string;
   outputFileListPaths?: string[];
   outputPaths?: string[];
-  runOnlyForDeploymentPostprocessing?: number;
   shellPath?: string;
   shellScript?: string;
 }
@@ -487,15 +513,25 @@ interface ContainerItemProxyProperties extends PbxprojObject {
   remoteInfo?: string;
 }
 /**
- * Properties of an `XCRemoteSwiftPackageReference` or
- * `XCLocalSwiftPackageReference`. Remote references carry the repository
- * and requirement. Local ones carry the relative path.
+ * Properties shared by the Swift package reference kinds. The remote and
+ * local interfaces below add their own keys.
  */
-interface SwiftPackageReferenceProperties extends PbxprojObject {
-  relativePath?: string;
+interface SwiftPackageReferenceProperties extends PbxprojObject {}
+/**
+ * Properties of an `XCRemoteSwiftPackageReference`, which names a
+ * repository and a version requirement.
+ */
+interface RemoteSwiftPackageReferenceProperties extends SwiftPackageReferenceProperties {
   repositoryURL?: string;
   requirement?: PbxprojObject;
 }
+/**
+ * Properties of an `XCLocalSwiftPackageReference`, which names a package
+ * directory relative to the project.
+ */
+interface LocalSwiftPackageReferenceProperties extends SwiftPackageReferenceProperties {
+  relativePath?: string;
+}
 /**
  * Properties of an `XCSwiftPackageProductDependency`.
  */
@@ -504,14 +540,28 @@ interface SwiftPackageProductDependencyProperties extends PbxprojObject {
   productName?: string;
 }
 /**
- * Properties of a `PBXFileSystemSynchronizedBuildFileExceptionSet` or its
- * build-phase-membership variant.
+ * Properties shared by the synchronized-folder exception set kinds.
  */
 interface ExceptionSetProperties extends PbxprojObject {
-  buildPhase?: string;
   membershipExceptions?: string[];
   target?: string;
 }
+/**
+ * Properties of a
+ * `PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet`, which
+ * adds the build phase the listed files belong to.
+ */
+interface BuildPhaseMembershipExceptionSetProperties extends ExceptionSetProperties {
+  buildPhase?: string;
+}
+/**
+ * Properties of a `PBXBuildStyle`, the pre-Xcode-2 predecessor of
+ * `XCBuildConfiguration` still found in old documents.
+ */
+interface BuildStyleProperties extends PbxprojObject {
+  buildSettings?: BuildSettings;
+  name?: string;
+}
 //#endregion
 //#region src/model/target.d.ts
 /**
@@ -526,15 +576,20 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
    * The target's name, when present.
    */
   get name(): string | undefined;
+  /**
+   * The view of the target's configuration list, when the reference
+   * resolves.
+   */
+  configurationList(): ConfigurationList | undefined;
   /**
    * The views of the target's build configurations, in list order.
    */
-  buildConfigurations(): XcodeObject[];
+  buildConfigurations(): BuildConfiguration[];
   /**
-   * The settings dictionary of the target's default configuration: the one
-   * named by the list's `defaultConfigurationName`, falling back to the
-   * first configuration. Returns `undefined` when the target has no
-   * configurations or the default carries no settings dictionary.
+   * The settings dictionary of the target's default configuration, which
+   * is the one named by the list's `defaultConfigurationName`, falling
+   * back to the first configuration. Returns `undefined` when the target
+   * has no configurations or the default carries no settings dictionary.
    */
   defaultConfigurationSettings(): PbxprojObject | undefined;
   /**
@@ -558,29 +613,31 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
    */
   removeBuildSetting(key: string): void;
   /**
-   * The views of the target's dependency objects
-   * (`PBXTargetDependency`), in declaration order. Resolve a dependency's
-   * target through its `target` property.
+   * The views of the target's dependencies, in declaration order. Resolve
+   * a dependency's target through {@link TargetDependency.target}.
    */
-  dependencies(): XcodeObject[];
+  dependencies(): TargetDependency[];
   /**
    * The views of the target's build phases, in build order.
    */
   buildPhases(): BuildPhase[];
   /**
    * Finds the target's first build phase with the given isa, and, when
-   * `name` is provided, the given display name.
+   * `name` is provided, the given display name. An isa literal of the
+   * vocabulary types the result, so `findBuildPhase(Isa.copyFilesBuildPhase)`
+   * gives a `CopyFilesBuildPhase | undefined`.
    */
-  findBuildPhase(isa: string, name?: string): BuildPhase | undefined;
+  findBuildPhase<I extends string>(isa: I, name?: string): BuildPhaseOf<I> | undefined;
   /**
    * Returns the target's build phase with the given isa and properties,
    * creating and appending it when missing. The properties apply only on
-   * creation; an existing phase is returned as is.
+   * creation. An existing phase is returned as is, already typed as the
+   * phase class the isa names.
    *
    * The match key is the isa plus the `name` property when one is given,
    * so differently named copy-files phases coexist.
    */
-  ensureBuildPhase(isa: string, properties?: PbxprojObject): BuildPhase;
+  ensureBuildPhase<I extends BuildPhaseIsa>(isa: I, properties?: PbxprojObject): BuildPhaseOf<I>;
   /**
    * The target's shell-script phase with the given name, created with the
    * usual defaults (`/bin/sh`, empty input and output lists) when missing.
@@ -589,7 +646,7 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
    * @param name Display name of the phase, which is also its match key.
    * @param properties Phase properties, most usefully `shellScript`.
    */
-  ensureShellScriptPhase(name: string, properties?: PbxprojObject): BuildPhase;
+  ensureShellScriptPhase(name: string, properties?: PbxprojObject): ShellScriptBuildPhase;
   /**
    * Adds a dependency on another target of the same project, wiring the
    * `PBXContainerItemProxy` and `PBXTargetDependency` pair Xcode uses to
@@ -597,13 +654,14 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
    *
    * @returns The view of the target dependency object.
    */
-  addDependency(dependency: Target): XcodeObject;
+  addDependency(dependency: Target): TargetDependency;
 }
 /**
  * A `PBXNativeTarget` is a product the project compiles and packages
  * itself, such as an application or an app extension.
  */
 declare class NativeTarget extends Target<NativeTargetProperties> {
+  static readonly isa: string | null;
   /**
    * The target's product type identifier, for example
    * `com.apple.product-type.application`.
@@ -618,7 +676,7 @@ declare class NativeTarget extends Target<NativeTargetProperties> {
    * The view of the target's product file reference, when the target has
    * one.
    */
-  get productReference(): XcodeObject | undefined;
+  get productReference(): FileReference | undefined;
   /**
    * Whether the target builds for watchOS, decided by its product type or
    * its watchOS deployment-target setting.
@@ -628,7 +686,7 @@ declare class NativeTarget extends Target<NativeTargetProperties> {
    * The views of the target's Swift package product dependencies, in
    * declaration order.
    */
-  packageProductDependencies(): XcodeObject[];
+  packageProductDependencies(): SwiftPackageProductDependency[];
   /**
    * The views of the target's file-system-synchronized folders, in
    * declaration order.
@@ -642,15 +700,15 @@ declare class NativeTarget extends Target<NativeTargetProperties> {
   /**
    * The target's sources phase, created when missing.
    */
-  ensureSourcesPhase(): BuildPhase;
+  ensureSourcesPhase(): SourcesBuildPhase;
   /**
    * The target's frameworks phase, created when missing.
    */
-  ensureFrameworksPhase(): BuildPhase;
+  ensureFrameworksPhase(): FrameworksBuildPhase;
   /**
    * The target's resources phase, created when missing.
    */
-  ensureResourcesPhase(): BuildPhase;
+  ensureResourcesPhase(): ResourcesBuildPhase;
   /**
    * Embeds another target's product into this target through the
    * copy-files phase its product type calls for ("Embed Foundation
@@ -664,7 +722,7 @@ declare class NativeTarget extends Target<NativeTargetProperties> {
    * @returns The view of the embed phase, or `undefined` when the embedded
    *   target has no product reference to embed.
    */
-  embed(extension: NativeTarget): BuildPhase | undefined;
+  embed(extension: NativeTarget): CopyFilesBuildPhase | undefined;
   /**
    * The on-disk folder paths of the file-system-synchronized groups linked
    * to this target. Empty for targets without synchronized folders
@@ -699,7 +757,7 @@ declare class NativeTarget extends Target<NativeTargetProperties> {
   addSwiftPackageProduct(options: {
     productName: string;
     packageReference: XcodeObject;
-  }): XcodeObject;
+  }): SwiftPackageProductDependency;
   /**
    * Links a system framework (for example `Messages`) to this target. It
    * reuses or creates the file reference under the SDK's frameworks
@@ -709,19 +767,22 @@ declare class NativeTarget extends Target<NativeTargetProperties> {
    * @param name Framework name without the `.framework` suffix.
    * @returns The view of the framework's file reference.
    */
-  addSystemFramework(name: string): XcodeObject;
+  addSystemFramework(name: string): FileReference;
 }
 /**
  * An aggregate target produces nothing itself. It exists to group other
  * targets through its dependencies and to run script or copy-files
  * phases, and the shared target surface covers everything it carries.
  */
-declare class AggregateTarget extends Target {}
+declare class AggregateTarget extends Target {
+  static readonly isa: string | null;
+}
 /**
  * A legacy target shells out to an external build tool such as make
  * instead of using Xcode's build system.
  */
 declare class LegacyTarget extends Target<LegacyTargetProperties> {
+  static readonly isa: string | null;
   /**
    * The build tool the target invokes, as an absolute path.
    */
@@ -740,11 +801,11 @@ declare class LegacyTarget extends Target<LegacyTargetProperties> {
 //#region src/model/objects.d.ts
 /**
  * A `PBXGroup` is a folder in Xcode's navigator, holding references to
- * files and other groups. Variant groups (`PBXVariantGroup`) share this
- * view. The type parameter lets subclasses carry a more specific property
- * shape.
+ * files and other groups. The type parameter lets subclasses carry a more
+ * specific property shape.
  */
 declare class Group<Properties extends GroupProperties = GroupProperties> extends XcodeObject<Properties> {
+  static readonly isa: string | null;
   /**
    * Ids of the group's children, in navigator order. Non-string entries of
    * a malformed document are skipped.
@@ -786,11 +847,21 @@ declare class Group<Properties extends GroupProperties = GroupProperties> extend
    */
   createFile(path: string): XcodeObject;
 }
+/**
+ * A `PBXVariantGroup` holds the localized variants of one file, one child
+ * per language. Everything else behaves like a plain group.
+ */
+declare class VariantGroup extends Group {
+  static readonly isa: string | null;
+}
 /**
  * A build phase is an ordered list of build files processed by one step
- * of a target's build. Every `PBX*BuildPhase` kind shares this view.
+ * of a target's build. Every `PBX*BuildPhase` kind extends this view, and
+ * kinds without a class of their own still map here through the factory's
+ * suffix fallback. The type parameter lets subclasses carry a more
+ * specific property shape.
  */
-declare class BuildPhase extends XcodeObject<BuildPhaseProperties> {
+declare class BuildPhase<Properties extends BuildPhaseProperties = BuildPhaseProperties> extends XcodeObject<Properties> {
   /**
    * The phase's display name, when it carries an explicit one. Xcode names
    * copy-files and shell-script phases; the standard phases derive their
@@ -831,13 +902,102 @@ declare class BuildPhase extends XcodeObject<BuildPhaseProperties> {
   ensureBuildFile(reference: XcodeObject, options?: {
     referenceKey?: "fileRef" | "productRef";
     settings?: Record<string, string[] | string>;
-  }): XcodeObject;
+  }): BuildFile;
+}
+/**
+ * A `PBXSourcesBuildPhase` compiles the target's source files.
+ */
+declare class SourcesBuildPhase extends BuildPhase {
+  static readonly isa: string | null;
+}
+/**
+ * A `PBXFrameworksBuildPhase` links the target against frameworks,
+ * libraries, and Swift package products.
+ */
+declare class FrameworksBuildPhase extends BuildPhase {
+  static readonly isa: string | null;
+}
+/**
+ * A `PBXResourcesBuildPhase` copies the target's resources into the
+ * built product.
+ */
+declare class ResourcesBuildPhase extends BuildPhase {
+  static readonly isa: string | null;
+}
+/**
+ * A `PBXHeadersBuildPhase` installs a framework target's headers with
+ * their public, private, or project visibility.
+ */
+declare class HeadersBuildPhase extends BuildPhase {
+  static readonly isa: string | null;
+}
+/**
+ * A `PBXCopyFilesBuildPhase` copies its build files to a destination
+ * inside the built product, which is how extensions and watch apps embed.
+ */
+declare class CopyFilesBuildPhase extends BuildPhase<CopyFilesBuildPhaseProperties> {
+  static readonly isa: string | null;
+  /**
+   * The destination path inside the folder `dstSubfolderSpec` selects,
+   * when present.
+   */
+  get dstPath(): string | undefined;
+}
+/**
+ * A `PBXShellScriptBuildPhase` runs a script during the build.
+ */
+declare class ShellScriptBuildPhase extends BuildPhase<ShellScriptBuildPhaseProperties> {
+  static readonly isa: string | null;
+  /**
+   * The script's source text, when present.
+   */
+  get shellScript(): string | undefined;
+  /**
+   * The interpreter the script runs under, when present. Xcode's default
+   * is `/bin/sh`.
+   */
+  get shellPath(): string | undefined;
+}
+/**
+ * A `PBXRezBuildPhase` runs Rez, the classic Mac OS resource compiler,
+ * over `.r` files. Xcode's UI called it "Build Carbon Resources".
+ * Current Xcode no longer creates these phases, but old documents still
+ * carry them.
+ */
+declare class RezBuildPhase extends BuildPhase {
+  static readonly isa: string | null;
+}
+/**
+ * A `PBXAppleScriptBuildPhase` compiles AppleScript sources. Current
+ * Xcode no longer creates these, but old documents still carry them.
+ */
+declare class AppleScriptBuildPhase extends BuildPhase {
+  static readonly isa: string | null;
+}
+/**
+ * A `PBXBuildFile` places one file reference or package product inside
+ * one build phase, optionally with per-file settings.
+ */
+declare class BuildFile extends XcodeObject<BuildFileProperties> {
+  static readonly isa: string | null;
+  /**
+   * The view of the file reference the build file points at, when it
+   * points at one. Build files for Swift package products carry a
+   * `productRef` instead; see {@link productDependency}.
+   */
+  fileReference(): XcodeObject | undefined;
+  /**
+   * The view of the Swift package product dependency the build file
+   * points at, when it points at one.
+   */
+  productDependency(): SwiftPackageProductDependency | undefined;
 }
 /**
  * A `PBXFileSystemSynchronizedRootGroup` is an Xcode 16 folder whose
  * members are synchronized from disk instead of listed individually.
  */
 declare class SyncRootGroup extends XcodeObject<SyncRootGroupProperties> {
+  static readonly isa: string | null;
   /**
    * The group's on-disk folder path, when present.
    */
@@ -860,13 +1020,51 @@ declare class SyncRootGroup extends XcodeObject<SyncRootGroupProperties> {
    * @param membershipExceptions File names inside the folder to exclude.
    * @returns The view of the target's exception set for this folder.
    */
-  addMembershipExceptions(target: NativeTarget, membershipExceptions: string[]): XcodeObject;
+  addMembershipExceptions(target: NativeTarget, membershipExceptions: string[]): BuildFileExceptionSet;
+}
+/**
+ * Behavior shared by the synchronized-folder exception set kinds, which
+ * carve files out of a folder's automatic membership for one target. The
+ * type parameter lets subclasses carry a more specific property shape.
+ */
+declare class ExceptionSet<Properties extends ExceptionSetProperties = ExceptionSetProperties> extends XcodeObject<Properties> {
+  /**
+   * The file names the set excludes, in declaration order. Non-string
+   * entries of a malformed document are skipped.
+   */
+  get membershipExceptions(): string[];
+  /**
+   * The view of the target whose membership the set restricts, when the
+   * reference resolves.
+   */
+  target(): XcodeObject | undefined;
+}
+/**
+ * A `PBXFileSystemSynchronizedBuildFileExceptionSet` excludes files from
+ * a synchronized folder's automatic target membership.
+ */
+declare class BuildFileExceptionSet extends ExceptionSet {
+  static readonly isa: string | null;
+}
+/**
+ * A `PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet`
+ * assigns some of a synchronized folder's files to a different build
+ * phase than the automatic one.
+ */
+declare class BuildPhaseMembershipExceptionSet extends ExceptionSet<BuildPhaseMembershipExceptionSetProperties> {
+  static readonly isa: string | null;
+  /**
+   * The view of the build phase the listed files belong to, when the
+   * reference resolves.
+   */
+  buildPhase(): BuildPhase | undefined;
 }
 /**
  * A `PBXBuildRule` tells a target which compiler or script processes a
  * kind of file.
  */
 declare class BuildRule extends XcodeObject<BuildRuleProperties> {
+  static readonly isa: string | null;
   /**
    * The rule's script, when it is a script rule rather than a reference
    * to a compiler specification.
@@ -879,6 +1077,7 @@ declare class BuildRule extends XcodeObject<BuildRuleProperties> {
  * `currentVersion` names the active one.
  */
 declare class VersionGroup extends Group<VersionGroupProperties> {
+  static readonly isa: string | null;
   /**
    * The view of the active model version's file reference, when the group
    * names one.
@@ -895,6 +1094,7 @@ declare class VersionGroup extends Group<VersionGroupProperties> {
  * target or of the project, for example Debug or Release.
  */
 declare class BuildConfiguration extends XcodeObject<BuildConfigurationProperties> {
+  static readonly isa: string | null;
   /**
    * The configuration's name, when present.
    */
@@ -907,11 +1107,30 @@ declare class BuildConfiguration extends XcodeObject<BuildConfigurationPropertie
    */
   get buildSettings(): BuildSettings | undefined;
 }
+/**
+ * A `PBXBuildStyle` is the pre-Xcode-2 predecessor of
+ * `XCBuildConfiguration`. Current Xcode neither creates nor reads them,
+ * but old documents still carry them.
+ */
+declare class BuildStyle extends XcodeObject<BuildStyleProperties> {
+  static readonly isa: string | null;
+  /**
+   * The style's name, when present.
+   */
+  get name(): string | undefined;
+  /**
+   * The style's settings dictionary, or `undefined` when the style
+   * carries none. The dictionary is live. Writes through it land in the
+   * document.
+   */
+  get buildSettings(): BuildSettings | undefined;
+}
 /**
  * A `PBXFileReference` names one file on disk, from source files to the
  * built products themselves.
  */
 declare class FileReference extends XcodeObject<FileReferenceProperties> {
+  static readonly isa: string | null;
   /**
    * The reference's path, relative to its `sourceTree`, when present.
    */
@@ -927,17 +1146,96 @@ declare class FileReference extends XcodeObject<FileReferenceProperties> {
  * target dependency and the target it points at.
  */
 declare class ContainerItemProxy extends XcodeObject<ContainerItemProxyProperties> {
+  static readonly isa: string | null;
   /**
    * The display name of the object the proxy points at, when present.
    * For target dependencies this is the target's name.
    */
   get remoteInfo(): string | undefined;
 }
+/**
+ * A `PBXTargetDependency` records that one target must build before
+ * another, through a container item proxy naming the prerequisite.
+ */
+declare class TargetDependency extends XcodeObject<TargetDependencyProperties> {
+  static readonly isa: string | null;
+  /**
+   * The view of the target this dependency points at, when the reference
+   * resolves to one inside this document.
+   */
+  target(): XcodeObject | undefined;
+  /**
+   * The view of the dependency's container item proxy, when the reference
+   * resolves.
+   */
+  targetProxy(): ContainerItemProxy | undefined;
+}
+/**
+ * An `XCConfigurationList` owns the named build configurations of one
+ * target or of the project, plus the default configuration choice.
+ */
+declare class ConfigurationList extends XcodeObject<ConfigurationListProperties> {
+  static readonly isa: string | null;
+  /**
+   * The name of the configuration builds use when none is specified, when
+   * present.
+   */
+  get defaultConfigurationName(): string | undefined;
+  /**
+   * The views of the list's build configurations, in list order. Dangling
+   * ids and objects of other kinds are skipped.
+   */
+  configurations(): BuildConfiguration[];
+}
+/**
+ * Behavior shared by the Swift package reference kinds. The type
+ * parameter lets subclasses carry a more specific property shape.
+ */
+declare class SwiftPackageReference<Properties extends SwiftPackageReferenceProperties = SwiftPackageReferenceProperties> extends XcodeObject<Properties> {}
+/**
+ * An `XCRemoteSwiftPackageReference` names a package repository and a
+ * version requirement.
+ */
+declare class RemoteSwiftPackageReference extends SwiftPackageReference<RemoteSwiftPackageReferenceProperties> {
+  static readonly isa: string | null;
+  /**
+   * The package's repository URL, when present.
+   */
+  get repositoryURL(): string | undefined;
+}
+/**
+ * An `XCLocalSwiftPackageReference` names a package directory relative
+ * to the project.
+ */
+declare class LocalSwiftPackageReference extends SwiftPackageReference<LocalSwiftPackageReferenceProperties> {
+  static readonly isa: string | null;
+  /**
+   * The package's path relative to the project, when present.
+   */
+  get relativePath(): string | undefined;
+}
+/**
+ * An `XCSwiftPackageProductDependency` links one product of a Swift
+ * package to the target that consumes it.
+ */
+declare class SwiftPackageProductDependency extends XcodeObject<SwiftPackageProductDependencyProperties> {
+  static readonly isa: string | null;
+  /**
+   * The product's name as the package manifest declares it, when present.
+   */
+  get productName(): string | undefined;
+  /**
+   * The view of the package reference the product comes from, when the
+   * reference resolves. Products of local packages can omit it.
+   */
+  packageReference(): SwiftPackageReference | undefined;
+}
 /**
  * A `PBXReferenceProxy` stands in for a product built by a target of
  * another project referenced from this one.
  */
 declare class ReferenceProxy extends XcodeObject<ReferenceProxyProperties> {
+  static readonly isa: string | null;
   /**
    * The proxy's product path inside the other project's build directory,
    * when present.
@@ -947,7 +1245,7 @@ declare class ReferenceProxy extends XcodeObject<ReferenceProxyProperties> {
    * The view of the container item proxy that names the remote target,
    * when the reference resolves.
    */
-  remoteReference(): XcodeObject | undefined;
+  remoteReference(): ContainerItemProxy | undefined;
 }
 //#endregion
 //#region src/model/project.d.ts
@@ -956,6 +1254,7 @@ declare class ReferenceProxy extends XcodeObject<ReferenceProxyProperties> {
  * the main group, and the project-level configurations.
  */
 declare class RootProject extends XcodeObject<RootProjectProperties> {
+  static readonly isa: string | null;
   /**
    * Ids of the project's targets, in project order.
    */
@@ -975,7 +1274,7 @@ declare class RootProject extends XcodeObject<RootProjectProperties> {
    * The views of the project's Swift package references, remote and local,
    * in declaration order.
    */
-  packageReferences(): XcodeObject[];
+  packageReferences(): SwiftPackageReference[];
   /**
    * The group product references live in, creating it (and registering it
    * as the project's `productRefGroup`) when missing.
@@ -1079,17 +1378,20 @@ declare class XcodeProject {
    */
   generateId(seed: string): string;
   /**
-   * Adds an object to the document and returns its view.
+   * Adds an object to the document and returns its view. When the isa is
+   * a literal of the vocabulary, the returned view is already the exact
+   * class for it, so `add(Isa.fileReference, ...)` gives a `FileReference`
+   * with no cast at the call site.
    *
-   * @param isa The object's kind; written as the `isa` property.
+   * @param isa The object's kind, written as the `isa` property.
    * @param properties The object's remaining properties. The dictionary is
    *   stored as passed (not copied), with `isa` written first so the
    *   serialized entry leads with it.
-   * @param seed Seed for the deterministic id; defaults to the isa, which
+   * @param seed Seed for the deterministic id. Defaults to the isa, which
    *   is only sensible for singleton objects.
    * @returns The view of the created object.
    */
-  add(isa: string, properties: PbxprojObject, seed?: string): XcodeObject;
+  add<I extends string>(isa: I, properties: PbxprojObject, seed?: string): ViewOf<I>;
   /**
    * The view of the document's root `PBXProject` object.
    *
@@ -1131,7 +1433,7 @@ declare class XcodeProject {
   /**
    * Finds the remote Swift package reference for a repository URL.
    */
-  findSwiftPackage(repositoryUrl: string): XcodeObject | undefined;
+  findSwiftPackage(repositoryUrl: string): RemoteSwiftPackageReference | undefined;
   /**
    * Adds a remote Swift package reference and registers it on the project.
    * When the project already references the repository, the existing
@@ -1148,11 +1450,11 @@ declare class XcodeProject {
   addSwiftPackage(options: {
     repositoryURL: string;
     requirement: Record<string, string>;
-  }): XcodeObject;
+  }): RemoteSwiftPackageReference;
   /**
    * Finds the local Swift package reference for a directory path.
    */
-  findLocalSwiftPackage(relativePath: string): XcodeObject | undefined;
+  findLocalSwiftPackage(relativePath: string): LocalSwiftPackageReference | undefined;
   /**
    * Adds a local (path-based) Swift package reference and registers it on
    * the project, returning the existing reference when the path is already
@@ -1162,13 +1464,13 @@ declare class XcodeProject {
    * @param relativePath The package directory, relative to the project.
    * @returns The view of the package reference for the path.
    */
-  addLocalSwiftPackage(relativePath: string): XcodeObject;
+  addLocalSwiftPackage(relativePath: string): LocalSwiftPackageReference;
   /**
    * The views of every `PBXBuildFile` that points at the referenced object
    * through `fileRef` or `productRef`. Useful for relocating a product
    * between copy phases.
    */
-  buildFilesReferencing(reference: XcodeObject): XcodeObject[];
+  buildFilesReferencing(reference: XcodeObject): BuildFile[];
   /**
    * Validates the document's object graph and returns every problem
    * found. An empty array means the graph is structurally sound. The
@@ -1233,11 +1535,72 @@ declare class XcodeProject {
    */
   findFileReference(projectRelativePath: string): XcodeObject | undefined;
   /**
-   * Creates the typed view for an object, dispatching on its isa. Objects
-   * outside the typed vocabulary get the generic base view.
+   * Creates the typed view for an object, dispatching on the isa each
+   * view class declares. Unknown `PBX*BuildPhase` kinds still map to
+   * {@link BuildPhase}, and everything else outside the vocabulary gets
+   * the generic base view.
    */
   private createView;
 }
+/**
+ * The view class for every isa of the vocabulary. The runtime registry
+ * and the {@link ViewByIsa} type are both derived from this one object,
+ * so the class an object routes to and the class its isa literal promises
+ * are always the same. The `satisfies` clause keeps the object covering
+ * the whole vocabulary, and the model tests check that every entry agrees
+ * with its class's own `isa` declaration.
+ */
+declare const VIEWS: {
+  readonly PBXAggregateTarget: typeof AggregateTarget;
+  readonly PBXAppleScriptBuildPhase: typeof AppleScriptBuildPhase;
+  readonly XCBuildConfiguration: typeof BuildConfiguration;
+  readonly PBXBuildFile: typeof BuildFile;
+  readonly PBXBuildRule: typeof BuildRule;
+  readonly PBXBuildStyle: typeof BuildStyle;
+  readonly XCConfigurationList: typeof ConfigurationList;
+  readonly PBXContainerItemProxy: typeof ContainerItemProxy;
+  readonly PBXCopyFilesBuildPhase: typeof CopyFilesBuildPhase;
+  readonly PBXFileReference: typeof FileReference;
+  readonly PBXFileSystemSynchronizedBuildFileExceptionSet: typeof BuildFileExceptionSet;
+  readonly PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet: typeof BuildPhaseMembershipExceptionSet;
+  readonly PBXFileSystemSynchronizedRootGroup: typeof SyncRootGroup;
+  readonly PBXFrameworksBuildPhase: typeof FrameworksBuildPhase;
+  readonly PBXGroup: typeof Group;
+  readonly PBXHeadersBuildPhase: typeof HeadersBuildPhase;
+  readonly PBXLegacyTarget: typeof LegacyTarget;
+  readonly XCLocalSwiftPackageReference: typeof LocalSwiftPackageReference;
+  readonly PBXNativeTarget: typeof NativeTarget;
+  readonly PBXProject: typeof RootProject;
+  readonly PBXReferenceProxy: typeof ReferenceProxy;
+  readonly XCRemoteSwiftPackageReference: typeof RemoteSwiftPackageReference;
+  readonly PBXResourcesBuildPhase: typeof ResourcesBuildPhase;
+  readonly PBXRezBuildPhase: typeof RezBuildPhase;
+  readonly PBXShellScriptBuildPhase: typeof ShellScriptBuildPhase;
+  readonly PBXSourcesBuildPhase: typeof SourcesBuildPhase;
+  readonly XCSwiftPackageProductDependency: typeof SwiftPackageProductDependency;
+  readonly PBXTargetDependency: typeof TargetDependency;
+  readonly PBXVariantGroup: typeof VariantGroup;
+  readonly XCVersionGroup: typeof VersionGroup;
+};
+/**
+ * The view class each isa of the vocabulary maps to, as a type. Derived
+ * from the same {@link VIEWS} object the runtime registry is built from,
+ * which is what lets creation and lookup helpers return the exact class
+ * for an isa literal instead of a base class the caller has to cast.
+ */
+type ViewByIsa = { [I in keyof typeof VIEWS]: InstanceType<(typeof VIEWS)[I]> };
+/**
+ * The view type an isa literal resolves to. Literals of the vocabulary
+ * give the dedicated class, and anything else gives the generic
+ * `XcodeObject`.
+ */
+type ViewOf<I extends string> = I extends keyof ViewByIsa ? ViewByIsa[I] : XcodeObject;
+/**
+ * The build phase view an isa literal resolves to. Isas outside the
+ * vocabulary give the generic `BuildPhase`, matching the view factory's
+ * suffix fallback.
+ */
+type BuildPhaseOf<I extends string> = I extends keyof ViewByIsa ? Extract<ViewByIsa[I], BuildPhase> : BuildPhase;
 //#endregion
 //#region src/model/object.d.ts
 /**
@@ -1253,6 +1616,15 @@ declare class XcodeProject {
  * itself always reads through the narrowing accessors.
  */
 declare class XcodeObject<Properties extends PbxprojObject = PbxprojObject> {
+  /**
+   * The `isa` name this view class models. Each concrete view declares
+   * its own, the factory registry routes objects of that isa to the
+   * class, and the model tests keep the registry and these declarations
+   * in agreement. Classes that only share behavior, like this base class
+   * and the abstract target and phase bases, declare `null` and never
+   * route.
+   */
+  static readonly isa: string | null;
   /** The project this object belongs to. */
   readonly project: XcodeProject;
   /** The object's 24-character identifier (its key in `objects`). */
@@ -1574,4 +1946,4 @@ declare function parseXcscheme(text: string): XcschemeDocument;
  */
 declare function generateObjectId(seed: string, existing: ReadonlySet<string>): string;
 //#endregion
-export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, BuildConfiguration, type BuildConfigurationProperties, type BuildFileProperties, BuildPhase, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, BuildableReference, type ConfigurationListProperties, ContainerItemProxy, type ContainerItemProxyProperties, CopyFilesDestination, type CreateXcschemeOptions, type ExceptionSetProperties, FileReference, type FileReferenceProperties, Group, type GroupProperties, Isa, LegacyTarget, type LegacyTargetProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RootProject, type RootProjectProperties, type SwiftPackageProductDependencyProperties, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, type TargetDependencyProperties, type TargetProperties, VersionGroup, type VersionGroupProperties, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, type XcschemeComment, type XcschemeDocument, type XcschemeElement, type XcschemeNode, XcschemeParseError, buildPbxproj, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parsePbxproj, parseXcscheme, xcschemeElements };
+export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, AppleScriptBuildPhase, BuildConfiguration, type BuildConfigurationProperties, BuildFile, BuildFileExceptionSet, type BuildFileProperties, BuildPhase, type BuildPhaseIsa, BuildPhaseMembershipExceptionSet, type BuildPhaseMembershipExceptionSetProperties, type BuildPhaseOf, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, BuildStyle, type BuildStyleProperties, BuildableReference, ConfigurationList, type ConfigurationListProperties, ContainerItemProxy, type ContainerItemProxyProperties, CopyFilesBuildPhase, type CopyFilesBuildPhaseProperties, CopyFilesDestination, type CreateXcschemeOptions, ExceptionSet, type ExceptionSetProperties, FileReference, type FileReferenceProperties, FrameworksBuildPhase, Group, type GroupProperties, HeadersBuildPhase, Isa, type IsaValue, LegacyTarget, type LegacyTargetProperties, LocalSwiftPackageReference, type LocalSwiftPackageReferenceProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RemoteSwiftPackageReference, type RemoteSwiftPackageReferenceProperties, ResourcesBuildPhase, RezBuildPhase, RootProject, type RootProjectProperties, ShellScriptBuildPhase, type ShellScriptBuildPhaseProperties, SourcesBuildPhase, SwiftPackageProductDependency, type SwiftPackageProductDependencyProperties, SwiftPackageReference, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, TargetDependency, type TargetDependencyProperties, type TargetProperties, VariantGroup, VersionGroup, type VersionGroupProperties, type ViewByIsa, type ViewOf, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, type XcschemeComment, type XcschemeDocument, type XcschemeElement, type XcschemeNode, XcschemeParseError, buildPbxproj, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parsePbxproj, parseXcscheme, xcschemeElements };