Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts:
#	packages/host/apiproxy/README.i18n.yaml

packages/host/apiproxy/src/api/rpc-map.ts

@@ -57,6 +57,7 @@ export interface RpcMethodMap {
   'goal.complete': GoalsApi['complete']
   'goal.clear': GoalsApi['clear']
   'settings.describe': SettingsApi['describe']
+  'settings.openDocument': SettingsApi['openDocument']
   'settings.update': SettingsApi['update']
   'settings.replace': SettingsApi['replace']
   'settings.mutate': SettingsApi['mutate']

packages/host/apiproxy/src/api/settings.schema.ts

@@ -32,9 +32,18 @@ export const settingsDescribeRequestSchema = z.object({}) satisfies z.ZodType<Wi
 /** settings.describe response value. */
 export const settingsDescribeValueSchema = z.object({
   writable: z.boolean(),
+  hasDocument: z.boolean(),
   namespaces: z.array(settingsNamespaceViewSchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'settings.describe'>>>
 
+/** settings.openDocument request payload. */
+export const settingsOpenDocumentRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'settings.openDocument'>>>
+
+/** settings.openDocument response value. */
+export const settingsOpenDocumentValueSchema = z.object({
+  opened: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'settings.openDocument'>>>
+
 /** settings.update request payload. */
 export const settingsUpdateRequestSchema = z.object({
   ns: z.string().min(1),

packages/host/apiproxy/src/api/settings.ts

@@ -53,10 +53,26 @@ export type SettingsPathOpView =
 export interface SettingsApi {
   /**
    * Describe every registered namespace: redacted layered values plus the
-   * serialized schema a client renders its form from. `writable: false`
-   * (read-only provider) tells the client to disable every write control.
+   * serialized schema a client renders its form from. `hasDocument` reports
+   * whether a file-backed provider owns a local document without exposing its
+   * Host path. This method is loopback-only; `writable: false` (read-only
+   * provider) tells the client to disable every write control.
    */
-  describe(request: RpcRequest<{}>): Promise<RpcResponse<{ writable: boolean; namespaces: SettingsNamespaceView[] }>>
+  describe(request: RpcRequest<{}>): Promise<RpcResponse<{
+    writable: boolean
+    hasDocument: boolean
+    namespaces: SettingsNamespaceView[]
+  }>>
+
+  /**
+   * Materialize the configured local document when absent and ask the Host to
+   * hand it to the platform text-document opener. macOS forces a text editor;
+   * Linux and Windows use the desktop file association. The request carries
+   * no path, so the browser cannot choose an arbitrary Host filesystem target.
+   */
+  openDocument(
+    request: RpcRequest<{}>, signal: AbortSignal,
+  ): Promise<RpcResponse<{ opened: true }>>
 
   /**
    * Merge a patch into one namespace's user layer (validate → persist →