objcjs-types 0.7.0 → 0.7.1

package/dist/WebKit/WKURLSchemeHandler.d.ts

@@ -4,9 +4,9 @@ export interface _WKURLSchemeHandler {
     /**
      * Notifies your app to start loading the data for a particular resource represented by the URL scheme handler task. The web view invoking the method. The task that your app should start loading data for.
      */
-    webView$startURLSchemeTask$?(webView: _WKWebView, urlSchemeTask: _WKURLSchemeTask): void;
+    webView$startURLSchemeTask$(webView: _WKWebView, urlSchemeTask: _WKURLSchemeTask): void;
     /**
      * Notifies your app to stop handling a URL scheme handler task. The web view invoking the method. The task that your app should stop handling. After your app is told to stop loading data for a URL scheme handler task it must not perform any callbacks for that task. An exception will be thrown if any callbacks are made on the URL scheme handler task after your app has been told to stop loading for it.
      */
-    webView$stopURLSchemeTask$?(webView: _WKWebView, urlSchemeTask: _WKURLSchemeTask): void;
+    webView$stopURLSchemeTask$(webView: _WKWebView, urlSchemeTask: _WKURLSchemeTask): void;
 }

package/dist/WebKit/WKURLSchemeTask.d.ts

@@ -6,19 +6,19 @@ export interface _WKURLSchemeTask {
     /**
      * Set the current response object for the task. The response to use. This method must be called at least once for each URL scheme handler task. Cross-origin requests require CORS header fields. An exception will be thrown if you try to send a new response object after the task has already been completed. An exception will be thrown if your app has been told to stop loading this task via the registered WKURLSchemeHandler object.
      */
-    didReceiveResponse$?(response: _NSURLResponse): void;
+    didReceiveResponse$(response: _NSURLResponse): void;
     /**
      * Add received data to the task. The data to add. After a URL scheme handler task's final response object is received you should start sending it data. Each time this method is called the data you send will be appended to all previous data. An exception will be thrown if you try to send the task any data before sending it a response. An exception will be thrown if you try to send the task any data after the task has already been completed. An exception will be thrown if your app has been told to stop loading this task via the registered WKURLSchemeHandler object.
      */
-    didReceiveData$?(data: _NSData): void;
+    didReceiveData$(data: _NSData): void;
     /**
      * Mark the task as successfully completed. An exception will be thrown if you try to finish the task before sending it a response. An exception will be thrown if you try to mark a task completed after it has already been marked completed or failed. An exception will be thrown if your app has been told to stop loading this task via the registered WKURLSchemeHandler object.
      */
-    didFinish?(): void;
+    didFinish(): void;
     /**
      * Mark the task as failed. A description of the error that caused the task to fail. An exception will be thrown if you try to mark a task failed after it has already been marked completed or failed. An exception will be thrown if your app has been told to stop loading this task via the registered WKURLSchemeHandler object.
      */
-    didFailWithError$?(error: _NSError): void;
+    didFailWithError$(error: _NSError): void;
     /** The request to load for this task. */
-    request?(): _NSURLRequest;
+    request(): _NSURLRequest;
 }

package/dist/WebKit/WKWebExtensionContextNotificationUserInfoKey.d.ts

@@ -1,5 +1,6 @@
+import type { NSStringLiteral } from "../helpers.js";
 export declare const WKWebExtensionContextNotificationUserInfoKey: {
     readonly Permissions: "permissions";
     readonly MatchPatterns: "matchPatterns";
 };
-export type WKWebExtensionContextNotificationUserInfoKey = typeof WKWebExtensionContextNotificationUserInfoKey[keyof typeof WKWebExtensionContextNotificationUserInfoKey];
+export type WKWebExtensionContextNotificationUserInfoKey = NSStringLiteral<(typeof WKWebExtensionContextNotificationUserInfoKey)[keyof typeof WKWebExtensionContextNotificationUserInfoKey]> | (typeof WKWebExtensionContextNotificationUserInfoKey)[keyof typeof WKWebExtensionContextNotificationUserInfoKey];

package/dist/WebKit/WKWebExtensionDataType.d.ts

@@ -1,6 +1,7 @@
+import type { NSStringLiteral } from "../helpers.js";
 export declare const WKWebExtensionDataType: {
     readonly Local: "local";
     readonly Session: "session";
     readonly Synchronized: "synchronized";
 };
-export type WKWebExtensionDataType = typeof WKWebExtensionDataType[keyof typeof WKWebExtensionDataType];
+export type WKWebExtensionDataType = NSStringLiteral<(typeof WKWebExtensionDataType)[keyof typeof WKWebExtensionDataType]> | (typeof WKWebExtensionDataType)[keyof typeof WKWebExtensionDataType];

package/dist/WebKit/WKWebExtensionPermission.d.ts

@@ -1,3 +1,4 @@
+import type { NSStringLiteral } from "../helpers.js";
 export declare const WKWebExtensionPermission: {
     readonly ActiveTab: "activeTab";
     readonly Alarms: "alarms";
@@ -16,4 +17,4 @@ export declare const WKWebExtensionPermission: {
     readonly WebNavigation: "webNavigation";
     readonly WebRequest: "webRequest";
 };
-export type WKWebExtensionPermission = typeof WKWebExtensionPermission[keyof typeof WKWebExtensionPermission];
+export type WKWebExtensionPermission = NSStringLiteral<(typeof WKWebExtensionPermission)[keyof typeof WKWebExtensionPermission]> | (typeof WKWebExtensionPermission)[keyof typeof WKWebExtensionPermission];

package/dist/WebKit/WebDocumentRepresentation.d.ts

@@ -6,25 +6,25 @@ export interface _WebDocumentRepresentation {
     /**
      * Called soon after the document representation is created. The data source that is set.
      */
-    setDataSource$?(dataSource: _WebDataSource): void;
+    setDataSource$(dataSource: _WebDataSource): void;
     /**
      * Called when the data source has received data. The data that the data source has received. The data source that has received data.
      */
-    receivedData$withDataSource$?(data: _NSData, dataSource: _WebDataSource): void;
+    receivedData$withDataSource$(data: _NSData, dataSource: _WebDataSource): void;
     /**
      * Called when the data source has received an error. The error that the data source has received. The data source that has received the error.
      */
-    receivedError$withDataSource$?(error: _NSError, dataSource: _WebDataSource): void;
+    receivedError$withDataSource$(error: _NSError, dataSource: _WebDataSource): void;
     /**
      * Called when the data source has finished loading. The datasource that has finished loading.
      */
-    finishedLoadingWithDataSource$?(dataSource: _WebDataSource): void;
+    finishedLoadingWithDataSource$(dataSource: _WebDataSource): void;
     /** Returns true if the representation can provide document source. */
-    canProvideDocumentSource?(): boolean;
+    canProvideDocumentSource(): boolean;
     /**
      * Returns the textual source representation of the document. For HTML documents this is the original HTML source.
      */
-    documentSource?(): _NSString;
+    documentSource(): _NSString;
     /** Return the title for the document. */
-    title?(): _NSString;
+    title(): _NSString;
 }

package/dist/WebKit/WebDocumentSearching.d.ts

@@ -3,5 +3,5 @@ export interface _WebDocumentSearching {
     /**
      * Searches a document view for a string and highlights the string if it is found. The string to search for. YES to search forward, NO to seach backwards. YES to for case-sensitive search, NO for case-insensitive search. YES to wrap around, NO to avoid wrapping. YES if found, NO if not found.
      */
-    searchFor$direction$caseSensitive$wrap$?(string_: _NSString, forward: boolean, caseFlag: boolean, wrapFlag: boolean): boolean;
+    searchFor$direction$caseSensitive$wrap$(string_: _NSString, forward: boolean, caseFlag: boolean, wrapFlag: boolean): boolean;
 }

package/dist/WebKit/WebDocumentText.d.ts

@@ -2,17 +2,17 @@ import type { _NSAttributedString } from "../Foundation/NSAttributedString.js";
 import type { _NSString } from "../Foundation/NSString.js";
 export interface _WebDocumentText {
     /** YES if the document view support text encoding, NO if it doesn't. */
-    supportsTextEncoding?(): boolean;
+    supportsTextEncoding(): boolean;
     /** String that represents the entire document. */
-    string?(): _NSString;
+    string(): _NSString;
     /** Attributed string that represents the entire document. */
-    attributedString?(): _NSAttributedString;
+    attributedString(): _NSAttributedString;
     /** String that represents the current selection. */
-    selectedString?(): _NSString;
+    selectedString(): _NSString;
     /** Attributed string that represents the current selection. */
-    selectedAttributedString?(): _NSAttributedString;
+    selectedAttributedString(): _NSAttributedString;
     /** Selects all the text in the document. */
-    selectAll?(): void;
+    selectAll(): void;
     /** Causes a text selection to lose its selection. */
-    deselectAll?(): void;
+    deselectAll(): void;
 }

package/dist/WebKit/WebDocumentView.d.ts

@@ -4,23 +4,23 @@ export interface _WebDocumentView {
     /**
      * Called when the corresponding data source has been created. The corresponding data source.
      */
-    setDataSource$?(dataSource: _WebDataSource): void;
+    setDataSource$(dataSource: _WebDataSource): void;
     /**
      * Called when the corresponding data source has received data. The corresponding data source.
      */
-    dataSourceUpdated$?(dataSource: _WebDataSource): void;
+    dataSourceUpdated$(dataSource: _WebDataSource): void;
     /**
      * Called when WebKit has determined that the document view needs to layout. This method should simply set a flag and call layout from drawRect if the flag is YES. YES to cause a layout, no to not cause a layout.
      */
-    setNeedsLayout$?(flag: boolean): void;
+    setNeedsLayout$(flag: boolean): void;
     /**
      * Called when the document view must immediately layout. For simple views, setting the frame is a sufficient implementation of this method.
      */
-    layout?(): void;
+    layout(): void;
     /**
      * The host window for the document view. Called before the host window is set on the parent web view.
      */
-    viewWillMoveToHostWindow$?(hostWindow: _NSWindow): void;
+    viewWillMoveToHostWindow$(hostWindow: _NSWindow): void;
     /** Called after the host window is set on the parent web view. */
-    viewDidMoveToHostWindow?(): void;
+    viewDidMoveToHostWindow(): void;
 }

package/dist/WebKit/WebOpenPanelResultListener.d.ts

@@ -4,11 +4,11 @@ export interface _WebOpenPanelResultListener {
     /**
      * Call this method to return a filename from the file open panel. the path of the selected file
      */
-    chooseFilename$?(fileName: _NSString): void;
+    chooseFilename$(fileName: _NSString): void;
     /**
      * Call this method to return an array of filenames from the file open panel. an array of paths of selected files
      */
-    chooseFilenames$?(fileNames: _NSArray): void;
+    chooseFilenames$(fileNames: _NSArray): void;
     /** Call this method to indicate that the file open panel was cancelled. */
-    cancel?(): void;
+    cancel(): void;
 }

package/dist/WebKit/WebPolicyDecisionListener.d.ts

@@ -2,13 +2,13 @@ export interface _WebPolicyDecisionListener {
     /**
      * Use the resource If there remain more policy decisions to be made, then the next policy delegate method gets to decide. This will be either the next navigation policy delegate if there is a redirect, or the content policy delegate. If there are no more policy decisions to be made, the resource will be displayed inline if possible. If there is no view available to display the resource inline, then unableToImplementPolicyWithError:frame: will be called with an appropriate error. If a new window is going to be created for this navigation as a result of frame targeting, then it will be created once you call this method.
      */
-    use?(): void;
+    use(): void;
     /**
      * Download the resource instead of displaying it. This method is more than just a convenience because it allows an in-progress navigation to be converted to a download based on content type, without having to stop and restart the load.
      */
-    download?(): void;
+    download(): void;
     /**
      * Do nothing (but the client may choose to handle the request itself) A policy of ignore prevents WebKit from doing anything further with the load, however, the client is still free to handle the request in some other way, such as opening a new window, opening a new window behind the current one, opening the URL in an external app, revealing the location in Finder if a file URL, etc.
      */
-    ignore?(): void;
+    ignore(): void;
 }

package/dist/helpers.d.ts

@@ -1,11 +1,20 @@
 import type { NobjcObject } from "objc-js";
 import { type _NSArray, type _NSDictionary, type _NSString } from "./Foundation/index.js";
+declare const NS_STRING_LITERAL: unique symbol;
+/**
+ * NSString subtype that preserves the originating string literal in the type system.
+ *
+ * This is a compile-time brand only. At runtime it is still just an NSString.
+ */
+export interface NSStringLiteral<T extends string = string> extends _NSString {
+    readonly [NS_STRING_LITERAL]?: T;
+}
 /**
  * Create NSString from a JavaScript string
  * @param str The string object
  * @returns An NSString object
  */
-export declare function NSStringFromString(str: string): _NSString;
+export declare function NSStringFromString<T extends string>(str: T): NSStringLiteral<T>;
 /**
  * Combine NS_OPTIONS values using bitwise OR.
  *

package/generator/ast-parser.ts

@@ -9,6 +9,7 @@ export interface ObjCMethod {
   returnType: string;
   parameters: { name: string; type: string; blockParamNames?: string[] }[];
   isClassMethod: boolean;
+  isOptional: boolean;
   isDeprecated: boolean;
   deprecationMessage?: string;
   description?: string;
@@ -19,6 +20,7 @@ export interface ObjCProperty {
   type: string;
   readonly: boolean;
   isClassProperty: boolean;
+  isOptional: boolean;
   /** Whether the property is null_resettable (getter returns non-null, setter accepts null) */
   nullResettable: boolean;
   isDeprecated: boolean;
@@ -497,6 +499,58 @@ function scanForDeprecation(
   return { isDeprecated: false };
 }
 
+/**
+ * Update protocol required/optional state by scanning source lines between two
+ * member declarations. ObjC protocol members are required by default unless an
+ * `@optional` directive appears more recently than `@required`.
+ */
+function scanProtocolOptionalityInRange(
+  lines: string[] | undefined,
+  startLine: number,
+  endLine: number,
+  initialIsOptional: boolean
+): boolean {
+  if (!lines || startLine > endLine) return initialIsOptional;
+
+  let isOptional = initialIsOptional;
+  let inBlockComment = false;
+
+  for (let i = startLine; i <= endLine && i < lines.length; i++) {
+    let line = lines[i] ?? "";
+
+    // Strip block comments so `@optional` / `@required` in comments don't
+    // affect the protocol section state.
+    if (inBlockComment) {
+      const endIdx = line.indexOf("*/");
+      if (endIdx === -1) continue;
+      line = line.slice(endIdx + 2);
+      inBlockComment = false;
+    }
+
+    while (true) {
+      const startIdx = line.indexOf("/*");
+      if (startIdx === -1) break;
+      const endIdx = line.indexOf("*/", startIdx + 2);
+      if (endIdx === -1) {
+        line = line.slice(0, startIdx);
+        inBlockComment = true;
+        break;
+      }
+      line = line.slice(0, startIdx) + " " + line.slice(endIdx + 2);
+    }
+
+    const lineCommentIdx = line.indexOf("//");
+    if (lineCommentIdx !== -1) {
+      line = line.slice(0, lineCommentIdx);
+    }
+
+    if (/\B@optional\b/.test(line)) isOptional = true;
+    if (/\B@required\b/.test(line)) isOptional = false;
+  }
+
+  return isOptional;
+}
+
 // --- Block parameter name extraction from header source ---
 
 /**
@@ -806,6 +860,7 @@ export function parseAST(
       returnType,
       parameters,
       isClassMethod,
+      isOptional: false,
       isDeprecated: deprecated,
       deprecationMessage: sourceDeprecation.message,
       description
@@ -834,6 +889,7 @@ export function parseAST(
       type,
       readonly,
       isClassProperty,
+      isOptional: false,
       nullResettable,
       isDeprecated: deprecated,
       deprecationMessage: sourceDeprecation.message,
@@ -956,7 +1012,7 @@ export function parseProtocols(
     return node.inner.some((child) => child.kind === "UnavailableAttr");
   }
 
-  function extractMethod(node: ClangASTNode, contextFile?: string): ObjCMethod | null {
+  function extractMethod(node: ClangASTNode, isOptional: boolean, contextFile?: string): ObjCMethod | null {
     if (node.kind !== "ObjCMethodDecl") return null;
     if (node.isImplicit) return null;
     if (isUnavailable(node)) return null;
@@ -1004,13 +1060,14 @@ export function parseProtocols(
       returnType,
       parameters,
       isClassMethod,
+      isOptional,
       isDeprecated: deprecated,
       deprecationMessage: sourceDeprecation.message,
       description
     };
   }
 
-  function extractProperty(node: ClangASTNode, contextFile?: string): ObjCProperty | null {
+  function extractProperty(node: ClangASTNode, isOptional: boolean, contextFile?: string): ObjCProperty | null {
     if (node.kind !== "ObjCPropertyDecl") return null;
     if (node.isImplicit) return null;
 
@@ -1029,6 +1086,7 @@ export function parseProtocols(
       type,
       readonly,
       isClassProperty,
+      isOptional,
       nullResettable,
       isDeprecated: deprecated,
       deprecationMessage: sourceDeprecation.message,
@@ -1071,6 +1129,10 @@ export function parseProtocols(
     // Resolve the file path from the parent node for child context.
     // Fall back to walkContextFile (the running file tracker from walk()).
     const parentFile = getLocFile(node) ?? walkContextFile;
+    const protocolLines = resolveHeaderLines(node, headerLines, headerLinesMap, parentFile);
+    const protocolLine = getLocLine(node) ?? 1;
+    let lastScannedLine = protocolLine - 1;
+    let currentIsOptional = false;
 
     // Track selectors we've already added (to handle multiple declarations of the same protocol)
     const existingInstanceSelectors = new Set(proto.instanceMethods.map((m) => m.selector));
@@ -1078,8 +1140,18 @@ export function parseProtocols(
     const existingProperties = new Set(proto.properties.map((p) => p.name));
 
     for (const child of node.inner) {
+      const childLine = getLocLine(child);
+      if (childLine && childLine >= 1) {
+        currentIsOptional = scanProtocolOptionalityInRange(
+          protocolLines,
+          Math.max(lastScannedLine, 0),
+          childLine - 2,
+          currentIsOptional
+        );
+      }
+
       if (child.kind === "ObjCMethodDecl") {
-        const method = extractMethod(child, parentFile);
+        const method = extractMethod(child, currentIsOptional, parentFile);
         if (!method) continue;
 
         if (method.isClassMethod) {
@@ -1094,12 +1166,16 @@ export function parseProtocols(
           }
         }
       } else if (child.kind === "ObjCPropertyDecl") {
-        const prop = extractProperty(child, parentFile);
+        const prop = extractProperty(child, currentIsOptional, parentFile);
         if (prop && !existingProperties.has(prop.name)) {
           proto.properties.push(prop);
           existingProperties.add(prop.name);
         }
       }
+
+      if (childLine && childLine >= 1) {
+        lastScannedLine = childLine;
+      }
     }
   }
 

package/generator/custom.ts

@@ -587,7 +587,7 @@ function emitCustomProtocolFile(
   const instancePropertyNames = new Set(instanceProps.map((p) => p.name));
   const regularMethods = proto.instanceMethods.filter((m) => !instancePropertyNames.has(m.selector));
 
-  // Instance methods (optional)
+  // Instance methods
   if (regularMethods.length > 0) {
     lines.push("  // Instance methods");
     for (const method of regularMethods) {
@@ -605,21 +605,23 @@ function emitCustomProtocolFile(
         }
         params.push(`${safeName}: ${tsType}`);
       }
-      lines.push(`  ${jsName}?(${params.join(", ")}): ${returnType};`);
+      const optional = method.isOptional ? "?" : "";
+      lines.push(`  ${jsName}${optional}(${params.join(", ")}): ${returnType};`);
     }
   }
 
-  // Instance properties (optional getters)
+  // Instance properties
   if (instanceProps.length > 0) {
     if (regularMethods.length > 0) lines.push("");
     lines.push("  // Properties");
     for (const prop of instanceProps) {
       const tsType = mapReturnType(prop.type, proto.name);
-      lines.push(`  ${prop.name}?(): ${tsType};`);
+      const optional = prop.isOptional ? "?" : "";
+      lines.push(`  ${prop.name}${optional}(): ${tsType};`);
       if (!prop.readonly) {
         const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
         const paramType = mapParamType(prop.type, proto.name);
-        lines.push(`  ${setterName}?(value: ${paramType}): void;`);
+        lines.push(`  ${setterName}${optional}(value: ${paramType}): void;`);
       }
     }
   }
@@ -710,7 +712,8 @@ async function main(): Promise<void> {
       discovery.classes.size === 0 &&
       discovery.protocols.size === 0 &&
       discovery.integerEnums.size === 0 &&
-      discovery.stringEnums.size === 0
+      discovery.stringEnums.size === 0 &&
+      discovery.numericConstants.size === 0
     )
       continue;
 
@@ -720,10 +723,12 @@ async function main(): Promise<void> {
       protocols: [...discovery.protocols.keys()].sort(),
       integerEnums: [...discovery.integerEnums.keys()].sort(),
       stringEnums: [...discovery.stringEnums.keys()].sort(),
+      numericConstants: [...discovery.numericConstants.keys()].sort(),
       classHeaders: discovery.classes,
       protocolHeaders: discovery.protocols,
       integerEnumHeaders: discovery.integerEnums,
-      stringEnumHeaders: discovery.stringEnums
+      stringEnumHeaders: discovery.stringEnums,
+      numericConstantHeaders: discovery.numericConstants
     });
   }
 

package/generator/emitter.ts

@@ -546,7 +546,7 @@ function getMergedProtocols(
   interface Sig {
     returnType: string;
     paramTypes: string[];
-    /** Whether this signature came from a protocol (optional in TS) vs a class body (non-optional). */
+    /** Whether this signature is optional in TypeScript. */
     isOptional: boolean;
   }
   const inherited = new Map<string, Sig>();
@@ -684,7 +684,7 @@ function collectProtocolSignatures(
       sigs.set(jsName, {
         returnType: mapReturnType(method.returnType, containingClass),
         paramTypes: method.parameters.map((p) => mapParamType(p.type, containingClass)),
-        isOptional: true
+        isOptional: method.isOptional
       });
     }
   }
@@ -695,7 +695,7 @@ function collectProtocolSignatures(
       sigs.set(prop.name, {
         returnType: mapReturnType(prop.type, containingClass),
         paramTypes: [],
-        isOptional: true
+        isOptional: prop.isOptional
       });
     }
     if (!prop.readonly) {
@@ -708,7 +708,7 @@ function collectProtocolSignatures(
         sigs.set(setterName, {
           returnType: "void",
           paramTypes: [paramType],
-          isOptional: true
+          isOptional: prop.isOptional
         });
       }
     }
@@ -745,10 +745,8 @@ function checkProtocolConflicts(
     const retType = mapReturnType(method.returnType, containingClass);
     if (retType !== parentSig.returnType) return true;
 
-    // Protocol methods are emitted as optional (foo?()) but class methods are
-    // non-optional (foo()). TypeScript considers these "not identical" in an
-    // interface extends clause, producing TS2320.
-    if (!parentSig.isOptional) return true;
+    // TypeScript interface merging requires optionality to match.
+    if (method.isOptional !== parentSig.isOptional) return true;
 
     const paramTypes = method.parameters.map((p) => mapParamType(p.type, containingClass));
     if (paramTypes.length === parentSig.paramTypes.length) {
@@ -765,13 +763,13 @@ function checkProtocolConflicts(
     if (parentSig) {
       const tsType = mapReturnType(prop.type, containingClass);
       if (tsType !== parentSig.returnType) return true;
-      if (!parentSig.isOptional) return true;
+      if (prop.isOptional !== parentSig.isOptional) return true;
     }
     if (!prop.readonly) {
       const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
       const parentSetterSig = inherited.get(setterName);
       if (parentSetterSig) {
-        if (!parentSetterSig.isOptional) return true;
+        if (prop.isOptional !== parentSetterSig.isOptional) return true;
         let paramType = mapParamType(prop.type, containingClass);
         if (prop.nullResettable && !paramType.includes("| null")) {
           paramType = `${paramType} | null`;
@@ -1483,7 +1481,7 @@ export function emitProtocolFile(
   // Split properties into class and instance
   const instanceProps = proto.properties.filter((p) => !p.isClassProperty);
 
-  // Emit instance methods (all optional with ? syntax)
+  // Emit instance methods
   const instancePropertyNames = new Set(instanceProps.map((p) => p.name));
   const regularMethods = proto.instanceMethods.filter((m) => !instancePropertyNames.has(m.selector));
 
@@ -1512,11 +1510,12 @@ export function emitProtocolFile(
         selector: method.selector
       });
       if (jsdoc.length > 0) lines.push(...jsdoc);
-      lines.push(`  ${jsName}?(${params.join(", ")}): ${returnType};`);
+      const optional = method.isOptional ? "?" : "";
+      lines.push(`  ${jsName}${optional}(${params.join(", ")}): ${returnType};`);
     }
   }
 
-  // Emit instance properties (as optional getter methods)
+  // Emit instance properties
   if (instanceProps.length > 0) {
     if (regularMethods.length > 0) lines.push("");
     lines.push("  // Properties");
@@ -1528,7 +1527,8 @@ export function emitProtocolFile(
         deprecationMessage: prop.deprecationMessage
       });
       if (jsdoc.length > 0) lines.push(...jsdoc);
-      lines.push(`  ${prop.name}?(): ${tsType};`);
+      const optional = prop.isOptional ? "?" : "";
+      lines.push(`  ${prop.name}${optional}(): ${tsType};`);
       if (!prop.readonly) {
         const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
         let paramType = mapParamType(prop.type, proto.name);
@@ -1536,7 +1536,7 @@ export function emitProtocolFile(
         if (prop.nullResettable && !paramType.includes("| null")) {
           paramType = `${paramType} | null`;
         }
-        lines.push(`  ${setterName}?(value: ${paramType}): void;`);
+        lines.push(`  ${setterName}${optional}(value: ${paramType}): void;`);
       }
     }
   }
@@ -1641,6 +1641,8 @@ export function emitStringEnumFile(enumDef: ObjCStringEnum, _currentFrameworkNam
   const lines: string[] = [];
   lines.push(AUTOGEN_HEADER);
   lines.push("");
+  lines.push(`import type { NSStringLiteral } from "../helpers.js";`);
+  lines.push("");
 
   // Filter to values that were successfully resolved
   const resolvedValues = enumDef.values.filter((v) => v.value !== null);
@@ -1657,7 +1659,8 @@ export function emitStringEnumFile(enumDef: ObjCStringEnum, _currentFrameworkNam
     lines.push(`} as const;`);
 
     lines.push(`export type ${enumDef.name} =`);
-    lines.push(`  typeof ${enumDef.name}[keyof typeof ${enumDef.name}];`);
+    lines.push(`  | NSStringLiteral<(typeof ${enumDef.name})[keyof typeof ${enumDef.name}]>`);
+    lines.push(`  | (typeof ${enumDef.name})[keyof typeof ${enumDef.name}];`);
   } else {
     // Fallback: if no values could be resolved, emit short names as a JSDoc comment
     // and a type alias that accepts any string (for forward compatibility)
@@ -1668,7 +1671,7 @@ export function emitStringEnumFile(enumDef: ObjCStringEnum, _currentFrameworkNam
       lines.push(` * Values could not be resolved from the framework binary.`);
       lines.push(` */`);
     }
-    lines.push(`export type ${enumDef.name} = string;`);
+    lines.push(`export type ${enumDef.name} = NSStringLiteral<string>;`);
   }
 
   lines.push("");

package/generator/templates/helpers.ts

@@ -8,17 +8,27 @@ import {
   type _NSString
 } from "./Foundation/index.js";
 
+declare const NS_STRING_LITERAL: unique symbol;
+/**
+ * NSString subtype that preserves the originating string literal in the type system.
+ *
+ * This is a compile-time brand only. At runtime it is still just an NSString.
+ */
+export interface NSStringLiteral<T extends string = string> extends _NSString {
+  readonly [NS_STRING_LITERAL]?: T;
+}
+
 /**
  * Create NSString from a JavaScript string
  * @param str The string object
  * @returns An NSString object
  */
-export function NSStringFromString(str: string): _NSString {
+export function NSStringFromString<T extends string>(str: T): NSStringLiteral<T> {
   const nsString = NSString.stringWithUTF8String$(str);
   if (!nsString) {
     throw new Error(`Failed to create NSString from string: ${str}`);
   }
-  return nsString;
+  return nsString as NSStringLiteral<T>;
 }
 
 /**