@pstdio/sdk 0.24.1 → 0.25.0

package/dist/api/index.js

@@ -5229,7 +5229,19 @@ var listExtensionConnectionsResponseSchema = object({
   connections: array(extensionConnectionRecordSchema)
 });
 
-// ../pstdio-api-contracts/src/extensions/execute.ts
+// ../pstdio-api-contracts/src/extension-kernel/navigation-href.ts
+var isNavigationHref = (href) => {
+  if (typeof href !== "string")
+    return false;
+  try {
+    const { protocol } = new URL(href);
+    return protocol === "https:" || protocol === "http:";
+  } catch {
+    return false;
+  }
+};
+
+// ../pstdio-api-contracts/src/extensions/resource-ref.ts
 var extensionResourceRefSchema = object({
   shorthand: string2().optional(),
   type: string2(),
@@ -5240,6 +5252,54 @@ var extensionResourceRefSchema = object({
   extensionId: string2().optional(),
   metadata: serializableJsonObjectSchema.optional()
 });
+
+// ../pstdio-api-contracts/src/extensions/workbench-refs-metadata.ts
+var contributionRefSchema = (kind) => object({ extensionId: string2(), kind: literal(kind), id: string2() });
+var pageRefSchema = contributionRefSchema("page");
+var placementRefSchema = contributionRefSchema("placement");
+var modeRefSchema = contributionRefSchema("mode");
+var viewRefSchema = contributionRefSchema("view");
+var resourceKindRefSchema = contributionRefSchema("resource-kind");
+var pageSlotRefSchema = object({
+  kind: literal("page-slot"),
+  page: pageRefSchema,
+  id: string2()
+});
+var panelRefSchema = union([placementRefSchema, pageSlotRefSchema]);
+var commandTargetSchema = object({
+  command: contributionRefSchema("command"),
+  params: serializableJsonObjectSchema.optional()
+});
+
+// ../pstdio-api-contracts/src/extensions/navigation-target-metadata.ts
+var sectionSchema = object({
+  anchors: array(object({ id: string2(), heading: string2(), occurrence: number2().int().nonnegative().optional() }))
+});
+var pageTargetSchema = lazy(() => object({
+  kind: literal("page"),
+  page: pageRefSchema,
+  resource: extensionResourceRefSchema.optional(),
+  open: _enum(["preview", "pin"]).optional(),
+  section: sectionSchema.optional(),
+  parent: pageTargetSchema.optional()
+})).meta({ id: "WorkbenchMetadataPageTarget" });
+var navigationOperationSchema = union([
+  pageTargetSchema,
+  object({
+    kind: literal("panel"),
+    panel: panelRefSchema,
+    resource: extensionResourceRefSchema.optional(),
+    open: _enum(["preview", "pin"]).optional()
+  })
+]);
+var navigationTargetSchema = union([
+  navigationOperationSchema,
+  object({ kind: literal("command"), target: commandTargetSchema }),
+  object({ kind: literal("href"), href: string2().refine(isNavigationHref, "Expected an HTTP or HTTPS URL") }),
+  object({ kind: literal("compound"), targets: array(navigationOperationSchema).min(1) })
+]);
+
+// ../pstdio-api-contracts/src/extensions/execute.ts
 var extensionRepoContextSchema = object({
   projectId: string2(),
   repoId: string2(),
@@ -5309,10 +5369,12 @@ var commandDiagnosticSchema = object({
   commandId: string2().optional(),
   metadata: jsonObjectSchema.optional()
 });
+var responseNavigationTargetSchema = navigationTargetSchema;
 var commandOutcomeSchema = object({
   ok: boolean2(),
   status: _enum(["success", "rejected", "error"]),
   value: unknown().optional(),
+  navigationRequests: array(responseNavigationTargetSchema).optional(),
   code: string2().optional(),
   reason: string2().optional(),
   data: jsonObjectSchema.optional(),
@@ -5682,52 +5744,6 @@ var extensionCommandPaletteResourceRecordSchema = object({
   refreshEventIds: array(string2().min(1)).optional()
 });
 
-// ../pstdio-api-contracts/src/extensions/workbench-refs-metadata.ts
-var contributionRefSchema = (kind) => object({ extensionId: string2(), kind: literal(kind), id: string2() });
-var pageRefSchema = contributionRefSchema("page");
-var placementRefSchema = contributionRefSchema("placement");
-var modeRefSchema = contributionRefSchema("mode");
-var viewRefSchema = contributionRefSchema("view");
-var resourceKindRefSchema = contributionRefSchema("resource-kind");
-var pageSlotRefSchema = object({
-  kind: literal("page-slot"),
-  page: pageRefSchema,
-  id: string2()
-});
-var panelRefSchema = union([placementRefSchema, pageSlotRefSchema]);
-var commandTargetSchema = object({
-  command: contributionRefSchema("command"),
-  params: serializableJsonObjectSchema.optional()
-});
-
-// ../pstdio-api-contracts/src/extensions/navigation-target-metadata.ts
-var sectionSchema = object({
-  anchors: array(object({ id: string2(), heading: string2(), occurrence: number2().int().nonnegative().optional() }))
-});
-var pageTargetSchema = lazy(() => object({
-  kind: literal("page"),
-  page: pageRefSchema,
-  resource: extensionResourceRefSchema.optional(),
-  open: _enum(["preview", "pin"]).optional(),
-  section: sectionSchema.optional(),
-  parent: pageTargetSchema.optional()
-})).meta({ id: "WorkbenchMetadataPageTarget" });
-var navigationOperationSchema = union([
-  pageTargetSchema,
-  object({
-    kind: literal("panel"),
-    panel: panelRefSchema,
-    resource: extensionResourceRefSchema.optional(),
-    open: _enum(["preview", "pin"]).optional()
-  })
-]);
-var navigationTargetSchema = union([
-  navigationOperationSchema,
-  object({ kind: literal("command"), target: commandTargetSchema }),
-  object({ kind: literal("href"), href: string2() }),
-  object({ kind: literal("compound"), targets: array(navigationOperationSchema).min(1) })
-]);
-
 // ../pstdio-api-contracts/src/extensions/keybindings.ts
 var parsedKeybindingChordSchema = object({
   key: string2(),
@@ -6453,6 +6469,86 @@ var l10n = (key, defaultValue) => ({
   ...defaultValue === undefined ? {} : { default: defaultValue }
 });
 var isLocalizedString = (value) => typeof value === "object" && value !== null && ("$l10n" in value) && typeof value.$l10n === "string";
+// ../pstdio-api-contracts/src/extension-kernel/navigation.ts
+var isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+var isContributionRef = (value, kind) => isRecord(value) && value.kind === kind && typeof value.id === "string";
+var isResource = (value) => isRecord(value) && typeof value.type === "string" && typeof value.id === "string";
+var isOpenIntent = (value) => value === undefined || value === "preview" || value === "pin";
+var isPageTarget = (value, ancestors = new Set) => {
+  if (!isRecord(value) || value.kind !== "page" || !isContributionRef(value.page, "page"))
+    return false;
+  if (ancestors.has(value))
+    return false;
+  if (value.resource !== undefined && !isResource(value.resource))
+    return false;
+  if (value.section !== undefined && !isRecord(value.section))
+    return false;
+  if (!isOpenIntent(value.open))
+    return false;
+  if (value.parent === undefined)
+    return true;
+  const next = new Set(ancestors);
+  next.add(value);
+  return isPageTarget(value.parent, next);
+};
+var isPanelTarget = (value) => {
+  if (!isRecord(value) || value.kind !== "panel" || !isRecord(value.panel))
+    return false;
+  const panel = value.panel;
+  const validPanel = isContributionRef(panel, "placement") || panel.kind === "page-slot" && isContributionRef(panel.page, "page") && typeof panel.id === "string";
+  return validPanel && (value.resource === undefined || isResource(value.resource)) && isOpenIntent(value.open);
+};
+var isItemTarget = (value) => {
+  if (!isRecord(value))
+    return false;
+  if (value.kind === "page")
+    return isPageTarget(value);
+  if (value.kind === "panel")
+    return isPanelTarget(value);
+  if (value.kind === "href")
+    return isNavigationHref(value.href);
+  return value.kind === "command" && isRecord(value.target) && isContributionRef(value.target.command, "command") && (value.target.params === undefined || isRecord(value.target.params));
+};
+var isNavigationTarget = (value) => {
+  if (isItemTarget(value))
+    return true;
+  if (!isRecord(value) || value.kind !== "compound" || !Array.isArray(value.targets) || value.targets.length === 0) {
+    return false;
+  }
+  return value.targets.every((target) => isPageTarget(target) || isPanelTarget(target));
+};
+var withExtensionOwner = (ref, extensionId) => ref.extensionId !== undefined || extensionId === undefined ? ref : { ...ref, extensionId };
+var toPageTarget = (target, extensionId, projectId) => ({
+  ...target,
+  page: withExtensionOwner(target.page, extensionId),
+  ...target.resource ? { resource: qualifyResource(target.resource, extensionId, projectId) } : {},
+  ...target.parent ? { parent: toPageTarget(target.parent, extensionId, projectId) } : {}
+});
+var qualifyResource = (resource, extensionId, projectId) => ({
+  ...resource,
+  extensionId: resource.extensionId ?? extensionId,
+  projectId: resource.projectId ?? projectId
+});
+var qualifyNavigationTarget = (target, extensionId, projectId) => {
+  if (!isNavigationTarget(target))
+    throw new Error("Invalid navigation target.");
+  if (target.kind === "page")
+    return toPageTarget(target, extensionId, projectId);
+  if (target.kind === "panel")
+    return {
+      ...target,
+      panel: target.panel.kind === "page-slot" ? { ...target.panel, page: withExtensionOwner(target.panel.page, extensionId) } : withExtensionOwner(target.panel, extensionId),
+      ...target.resource ? { resource: qualifyResource(target.resource, extensionId, projectId) } : {}
+    };
+  if (target.kind === "command")
+    return { ...target, target: { ...target.target, command: withExtensionOwner(target.target.command, extensionId) } };
+  if (target.kind === "href")
+    return target;
+  return {
+    ...target,
+    targets: target.targets.map((item) => qualifyNavigationTarget(item, extensionId, projectId))
+  };
+};
 // ../pstdio-api-contracts/src/extension-kernel/package-asset.ts
 var packageAsset = (path, baseUrl) => ({
   kind: "package-asset",

package/dist/api.d.ts

@@ -180,6 +180,7 @@ declare const commandExecuteResponseSchema: z.ZodObject<{
             rejected: "rejected";
         }>;
         value: z.ZodOptional<z.ZodUnknown>;
+        navigationRequests: z.ZodOptional<z.ZodArray<z.ZodType<NavigationTarget, unknown, z.core.$ZodTypeInternals<NavigationTarget, unknown>>>>;
         code: z.ZodOptional<z.ZodString>;
         reason: z.ZodOptional<z.ZodString>;
         data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;

package/dist/client.d.ts

@@ -244,6 +244,7 @@ declare const commandExecuteResponseSchema: z.ZodObject<{
             rejected: "rejected";
         }>;
         value: z.ZodOptional<z.ZodUnknown>;
+        navigationRequests: z.ZodOptional<z.ZodArray<z.ZodType<NavigationTarget, unknown, z.core.$ZodTypeInternals<NavigationTarget, unknown>>>>;
         code: z.ZodOptional<z.ZodString>;
         reason: z.ZodOptional<z.ZodString>;
         data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;

package/dist/data.d.ts

@@ -10,6 +10,8 @@ declare interface ArtifactMount {
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
     writeText(path: string, value: string): Promise<void>;
+    /** Replace existing text. Fails if missing and never recreates a concurrently deleted file. */
+    updateText(path: string, value: string): Promise<void>;
     readBytes(path: string): Promise<Uint8Array>;
     writeBytes(path: string, value: Uint8Array): Promise<void>;
     list(pattern?: string): Promise<ArtifactFile[]>;

package/dist/extensions/index.js

@@ -163,6 +163,98 @@ var l10n = (key, defaultValue) => ({
   ...defaultValue === undefined ? {} : { default: defaultValue }
 });
 var isLocalizedString = (value) => typeof value === "object" && value !== null && ("$l10n" in value) && typeof value.$l10n === "string";
+// ../pstdio-api-contracts/src/extension-kernel/navigation-href.ts
+var isNavigationHref = (href) => {
+  if (typeof href !== "string")
+    return false;
+  try {
+    const { protocol } = new URL(href);
+    return protocol === "https:" || protocol === "http:";
+  } catch {
+    return false;
+  }
+};
+
+// ../pstdio-api-contracts/src/extension-kernel/navigation.ts
+var isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+var isContributionRef = (value, kind) => isRecord(value) && value.kind === kind && typeof value.id === "string";
+var isResource = (value) => isRecord(value) && typeof value.type === "string" && typeof value.id === "string";
+var isOpenIntent = (value) => value === undefined || value === "preview" || value === "pin";
+var isPageTarget = (value, ancestors = new Set) => {
+  if (!isRecord(value) || value.kind !== "page" || !isContributionRef(value.page, "page"))
+    return false;
+  if (ancestors.has(value))
+    return false;
+  if (value.resource !== undefined && !isResource(value.resource))
+    return false;
+  if (value.section !== undefined && !isRecord(value.section))
+    return false;
+  if (!isOpenIntent(value.open))
+    return false;
+  if (value.parent === undefined)
+    return true;
+  const next = new Set(ancestors);
+  next.add(value);
+  return isPageTarget(value.parent, next);
+};
+var isPanelTarget = (value) => {
+  if (!isRecord(value) || value.kind !== "panel" || !isRecord(value.panel))
+    return false;
+  const panel = value.panel;
+  const validPanel = isContributionRef(panel, "placement") || panel.kind === "page-slot" && isContributionRef(panel.page, "page") && typeof panel.id === "string";
+  return validPanel && (value.resource === undefined || isResource(value.resource)) && isOpenIntent(value.open);
+};
+var isItemTarget = (value) => {
+  if (!isRecord(value))
+    return false;
+  if (value.kind === "page")
+    return isPageTarget(value);
+  if (value.kind === "panel")
+    return isPanelTarget(value);
+  if (value.kind === "href")
+    return isNavigationHref(value.href);
+  return value.kind === "command" && isRecord(value.target) && isContributionRef(value.target.command, "command") && (value.target.params === undefined || isRecord(value.target.params));
+};
+var isNavigationTarget = (value) => {
+  if (isItemTarget(value))
+    return true;
+  if (!isRecord(value) || value.kind !== "compound" || !Array.isArray(value.targets) || value.targets.length === 0) {
+    return false;
+  }
+  return value.targets.every((target) => isPageTarget(target) || isPanelTarget(target));
+};
+var withExtensionOwner = (ref, extensionId) => ref.extensionId !== undefined || extensionId === undefined ? ref : { ...ref, extensionId };
+var toPageTarget = (target, extensionId, projectId) => ({
+  ...target,
+  page: withExtensionOwner(target.page, extensionId),
+  ...target.resource ? { resource: qualifyResource(target.resource, extensionId, projectId) } : {},
+  ...target.parent ? { parent: toPageTarget(target.parent, extensionId, projectId) } : {}
+});
+var qualifyResource = (resource, extensionId, projectId) => ({
+  ...resource,
+  extensionId: resource.extensionId ?? extensionId,
+  projectId: resource.projectId ?? projectId
+});
+var qualifyNavigationTarget = (target, extensionId, projectId) => {
+  if (!isNavigationTarget(target))
+    throw new Error("Invalid navigation target.");
+  if (target.kind === "page")
+    return toPageTarget(target, extensionId, projectId);
+  if (target.kind === "panel")
+    return {
+      ...target,
+      panel: target.panel.kind === "page-slot" ? { ...target.panel, page: withExtensionOwner(target.panel.page, extensionId) } : withExtensionOwner(target.panel, extensionId),
+      ...target.resource ? { resource: qualifyResource(target.resource, extensionId, projectId) } : {}
+    };
+  if (target.kind === "command")
+    return { ...target, target: { ...target.target, command: withExtensionOwner(target.target.command, extensionId) } };
+  if (target.kind === "href")
+    return target;
+  return {
+    ...target,
+    targets: target.targets.map((item) => qualifyNavigationTarget(item, extensionId, projectId))
+  };
+};
 // ../pstdio-api-contracts/src/extension-kernel/package-asset.ts
 var packageAsset = (path, baseUrl) => ({
   kind: "package-asset",
@@ -200,7 +292,7 @@ var WEBVIEW_HOST_CAPABILITIES = [
   ...ALWAYS_AVAILABLE_WEBVIEW_CAPABILITIES
 ];
 // package.json
-var version = "0.24.1";
+var version = "0.25.0";
 
 // src/version.ts
 var SDK_VERSION = version;
@@ -733,6 +825,7 @@ export {
   extensionPanelRegions,
   gitEvents,
   isLocalizedString,
+  isNavigationTarget,
   isValidLocalContributionId,
   isWorkbenchProjectUrl,
   l10n,
@@ -746,6 +839,7 @@ export {
   projectEvents,
   projectPrefix,
   projectSlots,
+  qualifyNavigationTarget,
   qualifyRef,
   resolveEventReferenceId,
   resourceKey,

package/dist/extensions.d.ts

@@ -99,6 +99,8 @@ export declare interface ArtifactMount {
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
     writeText(path: string, value: string): Promise<void>;
+    /** Replace existing text. Fails if missing and never recreates a concurrently deleted file. */
+    updateText(path: string, value: string): Promise<void>;
     readBytes(path: string): Promise<Uint8Array>;
     writeBytes(path: string, value: Uint8Array): Promise<void>;
     list(pattern?: string): Promise<ArtifactFile[]>;
@@ -303,6 +305,7 @@ export declare type CommandOutcome<TResult = unknown> = {
     ok: true;
     status: "success";
     value: TResult;
+    navigationRequests?: NavigationTarget[];
     notices?: CommandNotice[];
     diagnostics?: CommandDiagnostic[];
 } | {
@@ -652,7 +655,7 @@ export declare interface DataTableRendererRowAction<TParams extends Struct = Str
 
 export declare type DataTableRendererRowActivationHandler = RendererCallback<{
     row: DataTableRendererRow;
-}, undefined | NavigationTarget>;
+}, void | NavigationTarget>;
 
 export declare interface DataTableRendererSelectionAction<TParams extends Struct = Struct> {
     id: string;
@@ -933,6 +936,10 @@ export declare interface ExtensionContextBase<TSettings extends Record<string, u
     source?: CommandSource;
     storage: ExtensionStorageApi;
     resources: ExtensionResourcesApi;
+    /** Records navigation for the invoking UI; headless execution opens nothing. */
+    navigation: {
+        open(target: NavigationTarget): void;
+    };
     artifacts: ExtensionArtifactApi;
     /** Working tree of the invocation's repo, scoped to its root. Absent for non-repo (event/hook) invocations. */
     repoFiles?: ArtifactMount;
@@ -1064,6 +1071,8 @@ export declare interface ExtensionReposApi {
 }
 
 export declare interface ExtensionResourcesApi {
+    /** Publish a committed removal to clients displaying this project resource. */
+    removed(resource: ResourceRef): Promise<void>;
     allocate(input: {
         kind: string;
     }): Promise<{
@@ -1173,6 +1182,8 @@ export declare interface ExtensionStorageCollectionApi<TItem = unknown> {
     get(id: string): Promise<TItem | undefined>;
     list(): Promise<TItem[]>;
     put(id: string, value: TItem): Promise<void>;
+    /** Replace an existing item atomically. Throws if the item was deleted. */
+    update(id: string, value: TItem): Promise<void>;
     createIfAbsent(id: string, value: TItem): Promise<boolean>;
     deleteIfValue(id: string, value: TItem): Promise<boolean>;
     create(value: TItem): Promise<TItem & {
@@ -1488,6 +1499,8 @@ export declare interface HookDefinition<TPayload extends Struct = Struct> extend
 
 export declare const isLocalizedString: (value: unknown) => value is LocalizedString;
 
+export declare const isNavigationTarget: (value: unknown) => value is NavigationTarget;
+
 export declare const isValidLocalContributionId: (id: string) => boolean;
 
 export declare const isWorkbenchProjectUrl: (urlValue: string, projectId: string) => boolean;
@@ -1646,7 +1659,7 @@ export declare interface KanbanRendererRowAction<TParams extends Struct = Struct
 
 export declare type KanbanRendererRowActivationHandler = RendererCallback<{
     row: KanbanRendererRow;
-}, undefined | NavigationTarget>;
+}, void | NavigationTarget>;
 
 export declare interface KanbanRendererSavedView {
     id: string;
@@ -2332,6 +2345,8 @@ export declare type QualifiedRef<Ref extends QualifiableRef> = Ref extends PageS
     readonly extensionId: string;
 };
 
+export declare const qualifyNavigationTarget: (target: NavigationTarget, extensionId: string, projectId?: string) => NavigationTarget;
+
 /** Publish a provider-owned reference without changing the local contribution definition. */
 export declare function qualifyRef<Ref extends QualifiableRef>(owner: string, ref: Ref): QualifiedRef<Ref>;
 
@@ -2552,6 +2567,11 @@ export declare interface ResourceRef {
 /** A reference the host can open (e.g. another resource tab). */
 export declare type ResourceRefValue = ResourceRef;
 
+export declare interface ResourceRemovedEvent {
+    id: string;
+    resource: ResourceRef;
+}
+
 export declare type ResourceRole = "primary" | "context" | "source" | "result";
 
 /** A reattach error is permanent unless the provider explicitly marks it retryable. */

package/dist/hooks.d.ts

@@ -242,6 +242,7 @@ declare const commandExecuteResponseSchema: z.ZodObject<{
             rejected: "rejected";
         }>;
         value: z.ZodOptional<z.ZodUnknown>;
+        navigationRequests: z.ZodOptional<z.ZodArray<z.ZodType<NavigationTarget, unknown, z.core.$ZodTypeInternals<NavigationTarget, unknown>>>>;
         code: z.ZodOptional<z.ZodString>;
         reason: z.ZodOptional<z.ZodString>;
         data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;

package/dist/resources/index.js

@@ -5229,7 +5229,19 @@ var listExtensionConnectionsResponseSchema = object({
   connections: array(extensionConnectionRecordSchema)
 });
 
-// ../pstdio-api-contracts/src/extensions/execute.ts
+// ../pstdio-api-contracts/src/extension-kernel/navigation-href.ts
+var isNavigationHref = (href) => {
+  if (typeof href !== "string")
+    return false;
+  try {
+    const { protocol } = new URL(href);
+    return protocol === "https:" || protocol === "http:";
+  } catch {
+    return false;
+  }
+};
+
+// ../pstdio-api-contracts/src/extensions/resource-ref.ts
 var extensionResourceRefSchema = object({
   shorthand: string2().optional(),
   type: string2(),
@@ -5240,6 +5252,54 @@ var extensionResourceRefSchema = object({
   extensionId: string2().optional(),
   metadata: serializableJsonObjectSchema.optional()
 });
+
+// ../pstdio-api-contracts/src/extensions/workbench-refs-metadata.ts
+var contributionRefSchema = (kind) => object({ extensionId: string2(), kind: literal(kind), id: string2() });
+var pageRefSchema = contributionRefSchema("page");
+var placementRefSchema = contributionRefSchema("placement");
+var modeRefSchema = contributionRefSchema("mode");
+var viewRefSchema = contributionRefSchema("view");
+var resourceKindRefSchema = contributionRefSchema("resource-kind");
+var pageSlotRefSchema = object({
+  kind: literal("page-slot"),
+  page: pageRefSchema,
+  id: string2()
+});
+var panelRefSchema = union([placementRefSchema, pageSlotRefSchema]);
+var commandTargetSchema = object({
+  command: contributionRefSchema("command"),
+  params: serializableJsonObjectSchema.optional()
+});
+
+// ../pstdio-api-contracts/src/extensions/navigation-target-metadata.ts
+var sectionSchema = object({
+  anchors: array(object({ id: string2(), heading: string2(), occurrence: number2().int().nonnegative().optional() }))
+});
+var pageTargetSchema = lazy(() => object({
+  kind: literal("page"),
+  page: pageRefSchema,
+  resource: extensionResourceRefSchema.optional(),
+  open: _enum(["preview", "pin"]).optional(),
+  section: sectionSchema.optional(),
+  parent: pageTargetSchema.optional()
+})).meta({ id: "WorkbenchMetadataPageTarget" });
+var navigationOperationSchema = union([
+  pageTargetSchema,
+  object({
+    kind: literal("panel"),
+    panel: panelRefSchema,
+    resource: extensionResourceRefSchema.optional(),
+    open: _enum(["preview", "pin"]).optional()
+  })
+]);
+var navigationTargetSchema = union([
+  navigationOperationSchema,
+  object({ kind: literal("command"), target: commandTargetSchema }),
+  object({ kind: literal("href"), href: string2().refine(isNavigationHref, "Expected an HTTP or HTTPS URL") }),
+  object({ kind: literal("compound"), targets: array(navigationOperationSchema).min(1) })
+]);
+
+// ../pstdio-api-contracts/src/extensions/execute.ts
 var extensionRepoContextSchema = object({
   projectId: string2(),
   repoId: string2(),
@@ -5309,10 +5369,12 @@ var commandDiagnosticSchema = object({
   commandId: string2().optional(),
   metadata: jsonObjectSchema.optional()
 });
+var responseNavigationTargetSchema = navigationTargetSchema;
 var commandOutcomeSchema = object({
   ok: boolean2(),
   status: _enum(["success", "rejected", "error"]),
   value: unknown().optional(),
+  navigationRequests: array(responseNavigationTargetSchema).optional(),
   code: string2().optional(),
   reason: string2().optional(),
   data: jsonObjectSchema.optional(),
@@ -5682,52 +5744,6 @@ var extensionCommandPaletteResourceRecordSchema = object({
   refreshEventIds: array(string2().min(1)).optional()
 });
 
-// ../pstdio-api-contracts/src/extensions/workbench-refs-metadata.ts
-var contributionRefSchema = (kind) => object({ extensionId: string2(), kind: literal(kind), id: string2() });
-var pageRefSchema = contributionRefSchema("page");
-var placementRefSchema = contributionRefSchema("placement");
-var modeRefSchema = contributionRefSchema("mode");
-var viewRefSchema = contributionRefSchema("view");
-var resourceKindRefSchema = contributionRefSchema("resource-kind");
-var pageSlotRefSchema = object({
-  kind: literal("page-slot"),
-  page: pageRefSchema,
-  id: string2()
-});
-var panelRefSchema = union([placementRefSchema, pageSlotRefSchema]);
-var commandTargetSchema = object({
-  command: contributionRefSchema("command"),
-  params: serializableJsonObjectSchema.optional()
-});
-
-// ../pstdio-api-contracts/src/extensions/navigation-target-metadata.ts
-var sectionSchema = object({
-  anchors: array(object({ id: string2(), heading: string2(), occurrence: number2().int().nonnegative().optional() }))
-});
-var pageTargetSchema = lazy(() => object({
-  kind: literal("page"),
-  page: pageRefSchema,
-  resource: extensionResourceRefSchema.optional(),
-  open: _enum(["preview", "pin"]).optional(),
-  section: sectionSchema.optional(),
-  parent: pageTargetSchema.optional()
-})).meta({ id: "WorkbenchMetadataPageTarget" });
-var navigationOperationSchema = union([
-  pageTargetSchema,
-  object({
-    kind: literal("panel"),
-    panel: panelRefSchema,
-    resource: extensionResourceRefSchema.optional(),
-    open: _enum(["preview", "pin"]).optional()
-  })
-]);
-var navigationTargetSchema = union([
-  navigationOperationSchema,
-  object({ kind: literal("command"), target: commandTargetSchema }),
-  object({ kind: literal("href"), href: string2() }),
-  object({ kind: literal("compound"), targets: array(navigationOperationSchema).min(1) })
-]);
-
 // ../pstdio-api-contracts/src/extensions/keybindings.ts
 var parsedKeybindingChordSchema = object({
   key: string2(),
@@ -6453,6 +6469,86 @@ var l10n = (key, defaultValue) => ({
   ...defaultValue === undefined ? {} : { default: defaultValue }
 });
 var isLocalizedString = (value) => typeof value === "object" && value !== null && ("$l10n" in value) && typeof value.$l10n === "string";
+// ../pstdio-api-contracts/src/extension-kernel/navigation.ts
+var isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+var isContributionRef = (value, kind) => isRecord(value) && value.kind === kind && typeof value.id === "string";
+var isResource = (value) => isRecord(value) && typeof value.type === "string" && typeof value.id === "string";
+var isOpenIntent = (value) => value === undefined || value === "preview" || value === "pin";
+var isPageTarget = (value, ancestors = new Set) => {
+  if (!isRecord(value) || value.kind !== "page" || !isContributionRef(value.page, "page"))
+    return false;
+  if (ancestors.has(value))
+    return false;
+  if (value.resource !== undefined && !isResource(value.resource))
+    return false;
+  if (value.section !== undefined && !isRecord(value.section))
+    return false;
+  if (!isOpenIntent(value.open))
+    return false;
+  if (value.parent === undefined)
+    return true;
+  const next = new Set(ancestors);
+  next.add(value);
+  return isPageTarget(value.parent, next);
+};
+var isPanelTarget = (value) => {
+  if (!isRecord(value) || value.kind !== "panel" || !isRecord(value.panel))
+    return false;
+  const panel = value.panel;
+  const validPanel = isContributionRef(panel, "placement") || panel.kind === "page-slot" && isContributionRef(panel.page, "page") && typeof panel.id === "string";
+  return validPanel && (value.resource === undefined || isResource(value.resource)) && isOpenIntent(value.open);
+};
+var isItemTarget = (value) => {
+  if (!isRecord(value))
+    return false;
+  if (value.kind === "page")
+    return isPageTarget(value);
+  if (value.kind === "panel")
+    return isPanelTarget(value);
+  if (value.kind === "href")
+    return isNavigationHref(value.href);
+  return value.kind === "command" && isRecord(value.target) && isContributionRef(value.target.command, "command") && (value.target.params === undefined || isRecord(value.target.params));
+};
+var isNavigationTarget = (value) => {
+  if (isItemTarget(value))
+    return true;
+  if (!isRecord(value) || value.kind !== "compound" || !Array.isArray(value.targets) || value.targets.length === 0) {
+    return false;
+  }
+  return value.targets.every((target) => isPageTarget(target) || isPanelTarget(target));
+};
+var withExtensionOwner = (ref, extensionId) => ref.extensionId !== undefined || extensionId === undefined ? ref : { ...ref, extensionId };
+var toPageTarget = (target, extensionId, projectId) => ({
+  ...target,
+  page: withExtensionOwner(target.page, extensionId),
+  ...target.resource ? { resource: qualifyResource(target.resource, extensionId, projectId) } : {},
+  ...target.parent ? { parent: toPageTarget(target.parent, extensionId, projectId) } : {}
+});
+var qualifyResource = (resource, extensionId, projectId) => ({
+  ...resource,
+  extensionId: resource.extensionId ?? extensionId,
+  projectId: resource.projectId ?? projectId
+});
+var qualifyNavigationTarget = (target, extensionId, projectId) => {
+  if (!isNavigationTarget(target))
+    throw new Error("Invalid navigation target.");
+  if (target.kind === "page")
+    return toPageTarget(target, extensionId, projectId);
+  if (target.kind === "panel")
+    return {
+      ...target,
+      panel: target.panel.kind === "page-slot" ? { ...target.panel, page: withExtensionOwner(target.panel.page, extensionId) } : withExtensionOwner(target.panel, extensionId),
+      ...target.resource ? { resource: qualifyResource(target.resource, extensionId, projectId) } : {}
+    };
+  if (target.kind === "command")
+    return { ...target, target: { ...target.target, command: withExtensionOwner(target.target.command, extensionId) } };
+  if (target.kind === "href")
+    return target;
+  return {
+    ...target,
+    targets: target.targets.map((item) => qualifyNavigationTarget(item, extensionId, projectId))
+  };
+};
 // ../pstdio-api-contracts/src/extension-kernel/package-asset.ts
 var packageAsset = (path, baseUrl) => ({
   kind: "package-asset",

package/dist/testing/index.js

@@ -1,5 +1,6 @@
 // src/testing/memory-resources.ts
 var createMemoryResources = (prefixes, sequences = new Map) => ({
+  removed: async () => {},
   allocate: async ({ kind }) => {
     const prefix = prefixes[kind];
     if (!prefix)
@@ -28,6 +29,7 @@ var makeCommandContext = (input) => {
     project: { id: projectId, name: "Test Project", shorthand: "T" },
     storage,
     resources,
+    navigation: { open: () => {} },
     invocation: { params },
     events: { emit: async () => ({ delivered: 0 }) },
     notify: { action: async () => ({}), dismiss: async () => [], resolve: async () => [], toast: async () => {} },
@@ -57,6 +59,11 @@ var createMemoryRepoFiles = () => {
     writeText: async (path, value) => {
       files.set(path, encoder.encode(value));
     },
+    updateText: async (path, value) => {
+      if (!files.has(path))
+        throw new Error(`File not found: ${path}`);
+      files.set(path, encoder.encode(value));
+    },
     readBytes: async (path) => {
       const value = files.get(path);
       if (value === undefined)
@@ -170,6 +177,11 @@ var createMemoryStorage = () => {
         async put(id, value) {
           store.set(id, value);
         },
+        async update(id, value) {
+          if (!store.has(id))
+            throw new Error(`Item not found: ${id}`);
+          store.set(id, value);
+        },
         async createIfAbsent(id, value) {
           if (store.has(id))
             return false;

package/dist/testing.d.ts

@@ -10,6 +10,8 @@ declare interface ArtifactMount {
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
     writeText(path: string, value: string): Promise<void>;
+    /** Replace existing text. Fails if missing and never recreates a concurrently deleted file. */
+    updateText(path: string, value: string): Promise<void>;
     readBytes(path: string): Promise<Uint8Array>;
     writeBytes(path: string, value: Uint8Array): Promise<void>;
     list(pattern?: string): Promise<ArtifactFile[]>;
@@ -88,6 +90,7 @@ declare type CommandOutcome<TResult = unknown> = {
     ok: true;
     status: "success";
     value: TResult;
+    navigationRequests?: NavigationTarget[];
     notices?: CommandNotice[];
     diagnostics?: CommandDiagnostic[];
 } | {
@@ -283,6 +286,10 @@ declare interface ExtensionContextBase<TSettings extends Record<string, unknown>
     source?: CommandSource;
     storage: ExtensionStorageApi;
     resources: ExtensionResourcesApi;
+    /** Records navigation for the invoking UI; headless execution opens nothing. */
+    navigation: {
+        open(target: NavigationTarget): void;
+    };
     artifacts: ExtensionArtifactApi;
     /** Working tree of the invocation's repo, scoped to its root. Absent for non-repo (event/hook) invocations. */
     repoFiles?: ArtifactMount;
@@ -394,6 +401,8 @@ declare interface ExtensionReposApi {
 }
 
 declare interface ExtensionResourcesApi {
+    /** Publish a committed removal to clients displaying this project resource. */
+    removed(resource: ResourceRef): Promise<void>;
     allocate(input: {
         kind: string;
     }): Promise<{
@@ -480,6 +489,8 @@ declare interface ExtensionStorageCollectionApi<TItem = unknown> {
     get(id: string): Promise<TItem | undefined>;
     list(): Promise<TItem[]>;
     put(id: string, value: TItem): Promise<void>;
+    /** Replace an existing item atomically. Throws if the item was deleted. */
+    update(id: string, value: TItem): Promise<void>;
     createIfAbsent(id: string, value: TItem): Promise<boolean>;
     deleteIfValue(id: string, value: TItem): Promise<boolean>;
     create(value: TItem): Promise<TItem & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pstdio/sdk",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/pufflyai/prompt-studio"