@pstdio/sdk 0.22.0 → 0.23.0

package/README.md

@@ -32,6 +32,32 @@ Page targets change location. Panel targets preserve it. Compound targets contai
 
 Use `qualifyRef(owner, ref)` in provider contract modules. Keep definitions local and pass qualified refs between extensions. For webviews, declare capabilities and call the typed `GuestHost`; `placement.close` closes the calling placement through the normal tab controller.
 
+## Dashboard URLs
+
+Use `serializePageUrl({ projectId, page, resource })` to return a dashboard link from a command. The page descriptor contains its `id`, qualified `ref`, and declared `path`; `resource` is optional. The workbench uses the same route and resource codec.
+
+Use `parsePageUrl({ url, projectId, pages })` to resolve a saved link against the expected project and allowed page descriptors. It accepts root-relative URLs and returns a page ID and optional resource, or `undefined` for an unsupported destination. It never fetches the URL. The caller still checks its supported resource kind and owner. A URL grants no access.
+
+Page and panel navigation targets remain the API for opening views and tabs.
+
+## Webview change subscriptions
+
+Use the typed client's `events.subscribe(event, listener)` to refetch after a command changes data:
+
+```ts
+const client = createWebviewClient<typeof commands>(host);
+const stop = client.events.subscribe(
+  { kind: "event", id: "notes.changed" },
+  () => void reloadNotes(),
+);
+// Dispose when the view unmounts.
+stop();
+```
+
+Local event refs use the client's extension owner: `{ kind: "event", id: "notes.changed" }` resolves to `<extensionId>.event.notes.changed`. Qualified event refs can name another extension in the same project. String IDs are already resolved and stay unchanged. Host-owned and command-lifecycle refs follow the runtime's rules through the shared `resolveEventReferenceId` helper. Commands emit events after committing their changes through `ctx.events.emit`.
+
+The host delivers only events matching the view's project. Projectless events reach global views only. Listeners also run when host sync connects or reconnects, so a mounted view can reconcile missed changes. Load current data when mounting, then subscribe; events are invalidations, not stored records or an exactly-once stream. Duplicate refetches must be safe. The subscription does not reload the webview document or grant new permissions.
+
 ## Package delivery
 
 Development and installed consumers both load built SDK entries. Repository development builds this package before starting the source CLI. Builds stage release files under `.publish` through the shared release script. Package verification installs those same staged artifacts into a temporary directory outside the monorepo and checks every entry point.

package/dist/client/index.js

@@ -499,21 +499,26 @@ var createSyncClient = (clientOptions) => ({
       if (event === "init")
         setConnected();
     };
+    const readConnection = async (signal) => {
+      const response = await resolveFetch(clientOptions)(resolveClientUrl(resolveBaseUrl(clientOptions), buildSyncStreamPath(lastSeq)), {
+        headers: Object.fromEntries(createRequestHeaders(clientOptions).entries()),
+        signal,
+        credentials: "same-origin"
+      });
+      if (!response.ok || !response.body)
+        throw new Error("SSE connection failed");
+      if (closed)
+        return;
+      if (lastSeq > 0)
+        setConnected();
+      await readSseStream(response.body, ({ event, data }) => handleEvent(event, data), { signal });
+    };
     const connect = async () => {
       if (closed)
         return;
       abortController = new AbortController;
       try {
-        const response = await resolveFetch(clientOptions)(resolveClientUrl(resolveBaseUrl(clientOptions), buildSyncStreamPath(lastSeq)), {
-          headers: Object.fromEntries(createRequestHeaders(clientOptions).entries()),
-          signal: abortController.signal,
-          credentials: "same-origin"
-        });
-        if (!response.ok || !response.body)
-          throw new Error("SSE connection failed");
-        await readSseStream(response.body, ({ event, data }) => handleEvent(event, data), {
-          signal: abortController.signal
-        });
+        await readConnection(abortController.signal);
       } catch (err) {
         if (closed || err.name === "AbortError")
           return;

package/dist/client.d.ts

@@ -1432,6 +1432,7 @@ export declare type SseEvent = {
 };
 
 export declare type StartSyncInput = SyncWriterProvider & {
+    /** Called after the initial snapshot, or when a cursor-based connection resumes. */
     onConnected?: () => void;
     onDisconnected?: () => void;
     onConnectionLost?: () => void;

package/dist/extensions/index.js

@@ -214,6 +214,11 @@ var WEBVIEW_HOST_CAPABILITIES = [
   ...WEBVIEW_SCOPED_DECLARABLE_CAPABILITIES,
   ...ALWAYS_AVAILABLE_WEBVIEW_CAPABILITIES
 ];
+// package.json
+var version = "0.23.0";
+
+// src/version.ts
+var SDK_VERSION = version;
 // src/extensions/command-outcome.ts
 var unwrapCommandOutcome = (response, fallbackReason = "Command failed.") => {
   const { outcome } = response;
@@ -340,6 +345,180 @@ var defineExtensionView = (definition) => ({
     return typeof cleanup === "function" ? cleanup : () => {};
   }
 });
+// src/extensions/event-reference.ts
+var resolveEventReferenceId = (ref, ownerExtensionId) => {
+  if (typeof ref === "string")
+    return ref;
+  const extensionId = ref.extensionId ?? ownerExtensionId;
+  if (!extensionId || extensionId === "pstdio")
+    return ref.id;
+  const lifecycle = /^(command\.(?:requested|started|completed|rejected|failed):)(.+)$/.exec(ref.id);
+  if (lifecycle)
+    return `${lifecycle[1]}${extensionId}.command.${lifecycle[2]}`;
+  return `${extensionId}.event.${ref.id}`;
+};
+// src/extensions/page-resource-codec.ts
+var fromUri = (uri) => {
+  try {
+    const parsed = new URL(uri);
+    if (parsed.protocol !== "pstdio:" || parsed.hostname !== "extension-resource")
+      return;
+    const [type, id, ...rest] = parsed.pathname.slice(1).split("/");
+    if (!type || !id || rest.length > 0)
+      return;
+    const extensionId = parsed.searchParams.get("extensionId");
+    const projectId = parsed.searchParams.get("projectId");
+    return {
+      type: decodeURIComponent(type),
+      id: decodeURIComponent(id),
+      ...extensionId ? { extensionId } : {},
+      ...projectId ? { projectId } : {}
+    };
+  } catch {
+    return;
+  }
+};
+var defaultPageResourceCodec = {
+  normalize: (resource) => ({ ...resource }),
+  toUri: (resource) => {
+    const uri = `pstdio://extension-resource/${encodeURIComponent(resource.type)}/${encodeURIComponent(resource.id)}`;
+    const query = new URLSearchParams;
+    if (resource.extensionId)
+      query.set("extensionId", resource.extensionId);
+    if (resource.projectId)
+      query.set("projectId", resource.projectId);
+    return query.size ? `${uri}?${query}` : uri;
+  },
+  fromUri
+};
+// src/extensions/page-url.ts
+var hostExtensionId = "pstdio";
+var pageRefKey = (ref) => `${ref.extensionId ?? ""}:page:${ref.id}`;
+var pageForRef = (pages, ref) => pages.find((page) => pageRefKey(page.ref) === pageRefKey(ref));
+var encodePath = (path) => path.split("/").filter(Boolean).map((segment) => encodeURIComponent(segment)).join("/");
+var routePath = (projectId, page) => {
+  const project = `/projects/${encodeURIComponent(projectId)}`;
+  const path = encodePath(page.path);
+  if (page.ref.extensionId === hostExtensionId)
+    return path ? `${project}/${path}` : project;
+  if (!page.ref.extensionId)
+    throw new Error(`Page "${page.id}" has no extension id`);
+  return `${project}/extensions/${encodeURIComponent(page.ref.extensionId)}/${path}`;
+};
+var normalizedSection = (value) => {
+  if (!value || typeof value !== "object" || !Array.isArray(value.anchors))
+    return;
+  const anchors = value.anchors;
+  if (anchors.some((anchor) => !anchor || typeof anchor !== "object" || typeof anchor.id !== "string" || typeof anchor.heading !== "string" || anchor.occurrence !== undefined && (!Number.isInteger(anchor.occurrence) || Number(anchor.occurrence) < 0))) {
+    return;
+  }
+  return {
+    anchors: anchors.map((anchor) => {
+      const value2 = anchor;
+      return {
+        id: value2.id,
+        heading: value2.heading,
+        ...value2.occurrence !== undefined ? { occurrence: value2.occurrence } : {}
+      };
+    })
+  };
+};
+var serializeSection = (section) => {
+  const normalized = normalizedSection(section);
+  if (!normalized)
+    throw new Error("Page location has an invalid section");
+  return JSON.stringify(normalized);
+};
+var parseSection = (value) => {
+  try {
+    return normalizedSection(JSON.parse(value));
+  } catch {
+    return;
+  }
+};
+var serializeWorkbenchPageUrl = (input) => {
+  const page = pageForRef(input.pages, input.location.page);
+  if (!page)
+    throw new Error(`Unknown page ref: ${pageRefKey(input.location.page)}`);
+  const query = new URLSearchParams;
+  if (input.location.resource) {
+    query.set("resource", input.resources.toUri(input.resources.normalize(input.location.resource)));
+  }
+  if (input.location.section)
+    query.set("section", serializeSection(input.location.section));
+  const encoded = query.toString();
+  const path = routePath(input.projectId, page);
+  return encoded ? `${path}?${encoded}` : path;
+};
+var decodedSegments = (pathname) => {
+  try {
+    return pathname.split("/").filter(Boolean).map((segment) => decodeURIComponent(segment));
+  } catch {
+    return;
+  }
+};
+var isWorkbenchProjectUrl = (urlValue, projectId) => {
+  try {
+    const url = new URL(urlValue, "http://workbench.local");
+    const segments = decodedSegments(url.pathname);
+    return Boolean(segments && segments[0] === "projects" && segments[1] === projectId);
+  } catch {
+    return false;
+  }
+};
+var pageForRoute = (pages, extensionId, path) => pages.find((page) => page.ref.extensionId === extensionId && page.path === path);
+var parseResource = (uri, resources) => {
+  try {
+    const resource = resources.fromUri(uri);
+    return resource ? resources.normalize(resource) : undefined;
+  } catch {
+    return;
+  }
+};
+var parseWorkbenchPageUrl = (input) => {
+  let url;
+  try {
+    url = new URL(input.url, "http://workbench.local");
+  } catch {
+    return;
+  }
+  const segments = decodedSegments(url.pathname);
+  if (!segments || segments[0] !== "projects" || segments[1] !== input.projectId)
+    return;
+  const route = segments.slice(2);
+  const extensionRoute = route[0] === "extensions";
+  const extensionId = extensionRoute ? route[1] : hostExtensionId;
+  const path = (extensionRoute ? route.slice(2) : route).join("/");
+  if (!extensionId || extensionRoute && !path)
+    return;
+  const page = pageForRoute(input.pages, extensionId, path);
+  if (!page)
+    return;
+  const resourceValue = url.searchParams.get("resource");
+  const resource = resourceValue ? parseResource(resourceValue, input.resources) : undefined;
+  if (resourceValue && !resource)
+    return;
+  const sectionValue = url.searchParams.get("section");
+  const section = sectionValue ? parseSection(sectionValue) : undefined;
+  if (sectionValue && !section)
+    return;
+  return {
+    pageId: page.id,
+    ...resource ? { resource } : {},
+    ...section ? { section } : {}
+  };
+};
+var serializePageUrl = (input) => serializeWorkbenchPageUrl({
+  projectId: input.projectId,
+  location: { page: input.page.ref, resource: input.resource },
+  pages: [input.page],
+  resources: defaultPageResourceCodec
+});
+var parsePageUrl = (input) => {
+  if (!input.url.startsWith("/") || input.url.startsWith("//"))
+    return;
+  return parseWorkbenchPageUrl({ ...input, resources: defaultPageResourceCodec });
+};
 // src/extensions/params.ts
 var params = {
   text: (options) => ({ type: "text", ...options }),
@@ -454,6 +633,19 @@ var createTerminalSessionBridge = (host) => ({
 // src/extensions/webview-capabilities.ts
 var artifactMountId = (mount) => typeof mount === "string" ? mount : mount.id;
 var artifactsRead = (mount) => `artifacts.read:${artifactMountId(mount)}`;
+// src/extensions/webview-events.ts
+var EXTENSION_EVENTS_SCOPE = "extension.events";
+var createWebviewEventsClient = (host, extensionId) => ({
+  subscribe(event, listener) {
+    const id = resolveEventReferenceId(event, extensionId);
+    return host.onEvent(EXTENSION_EVENTS_SCOPE, (payload) => {
+      const notification = payload;
+      if (notification.type === "reset" || notification.type === "changed" && notification.id === id)
+        listener();
+    });
+  }
+});
+
 // src/extensions/webview-client.ts
 var createWebviewClient = (host, options) => {
   const extensionId = options?.extensionId ?? host.extensionId;
@@ -490,7 +682,8 @@ var createWebviewClient = (host, options) => {
     readText: (mount, path) => host.call("artifacts.read", { op: "readText", mount: artifactMountId(mount), path }),
     imageUrl: (mount, path) => host.call("artifacts.read", { op: "imageUrl", mount: artifactMountId(mount), path })
   };
-  return { artifacts, commands, settings };
+  const events = createWebviewEventsClient(host, extensionId);
+  return { artifacts, commands, events, settings };
 };
 // src/extensions/when.ts
 var matchesResourceWhen = (when, resourceType) => {
@@ -515,17 +708,23 @@ export {
   unwrapCommandOutcome,
   sessionSlots,
   sessionEvents,
+  serializeWorkbenchPageUrl,
+  serializePageUrl,
   resourceMenuSlotRef2 as resourceMenuSlotRef,
   resourceKey,
+  resolveEventReferenceId,
   qualifyRef,
   projectSlots,
   projectEvents,
+  parseWorkbenchPageUrl,
+  parsePageUrl,
   params,
   packageAsset,
   matchesResourceWhen,
   localContributionIdPattern,
   localContributionIdGrammar,
   l10n,
+  isWorkbenchProjectUrl,
   isValidLocalContributionId,
   isLocalizedString,
   gitEvents,
@@ -564,6 +763,7 @@ export {
   defineCommand,
   defineArtifactMount,
   defineActivityItem,
+  defaultPageResourceCodec,
   createWebviewClient,
   createTerminalSessionBridge,
   commandRef,
@@ -574,6 +774,8 @@ export {
   WEBVIEW_HOST_CAPABILITY_VERSION,
   WEBVIEW_HOST_CAPABILITIES,
   WEBVIEW_DECLARABLE_CAPABILITIES,
+  SDK_VERSION,
+  EXTENSION_EVENTS_SCOPE,
   EXTENSION_API_VERSION,
   ALWAYS_AVAILABLE_WEBVIEW_CAPABILITIES
 };

package/dist/extensions.d.ts

@@ -680,6 +680,9 @@ export declare interface DateControl extends BaseControl {
     max?: string;
 }
 
+/** Resource URI conversion belongs to route and persistence adapters. */
+export declare const defaultPageResourceCodec: PageResourceCodec;
+
 export declare const defineActivityItem: <Definition extends Omit<ActivityItemContribution, "ref">>(definition: Definition) => Definition & ContributionDefinition<"activity-item">;
 
 export declare const defineArtifactMount: <Definition extends Omit<ArtifactMountContribution, "ref">>(definition: Definition) => Definition & ContributionDefinition<"artifact-mount">;
@@ -815,7 +818,7 @@ export declare interface EventRef<TPayload extends Struct = Struct> {
 /** Build a typed event reference from separate ownership and local identity. */
 export declare const eventRef: <TPayload extends Struct = Struct>(input: ExternalRefInput) => EventRef<TPayload>;
 
-declare type ExactOptions<Definition, Contract> = unknown extends Contract ? Definition : [Contract] extends [Definition] ? Definition : Contract extends unknown ? Definition extends Contract ? Contract extends EventRef ? Definition : Definition extends (...args: never[]) => unknown ? Definition : Definition extends readonly unknown[] ? Contract extends readonly (infer Item)[] ? {
+declare type ExactOptions<Definition, Contract> = unknown extends Contract ? Definition : [Contract] extends [Definition] ? Definition : Contract extends unknown ? Definition extends Contract ? Contract extends EventRef | CommandRef ? Definition : Definition extends (...args: never[]) => unknown ? Definition : Definition extends readonly unknown[] ? Contract extends readonly (infer Item)[] ? {
     [Index in keyof Definition]: ExactOptions<Definition[Index], Item>;
 } : never : Definition extends object ? {
     [Key in keyof Definition]: Key extends keyof Contract ? ExactOptions<Definition[Key], Contract[Key]> : never;
@@ -824,6 +827,8 @@ declare type ExactOptions<Definition, Contract> = unknown extends Contract ? Def
 /** Current host extension API version. `engines.pstdio` in package.json is a semver range checked against this. */
 export declare const EXTENSION_API_VERSION = "1.0.0-alpha.10";
 
+export declare const EXTENSION_EVENTS_SCOPE = "extension.events";
+
 export declare interface ExtensionActivityApi {
     record(input: {
         message: string;
@@ -1028,6 +1033,11 @@ export declare const extensionPanelRegions: readonly ["main", "secondary", "side
 export declare interface ExtensionProcessApi {
     run(input: ProcessRunInput): Promise<ProcessRunResult>;
     runOrThrow(input: ProcessRunInput): Promise<ProcessRunResult>;
+    /**
+     * Starts an independent process with no attached standard streams.
+     * It survives runtime and desktop shutdown and does not delay host exit.
+     * The extension owns the child's lifetime and must arrange its cleanup.
+     */
     spawnDetached(input: {
         command: string[];
         cwd?: string;
@@ -1470,6 +1480,8 @@ export declare const isLocalizedString: (value: unknown) => value is LocalizedSt
 
 export declare const isValidLocalContributionId: (id: string) => boolean;
 
+export declare const isWorkbenchProjectUrl: (urlValue: string, projectId: string) => boolean;
+
 export declare type JsonObject = {
     [key: string]: JsonValue;
 };
@@ -2028,6 +2040,12 @@ declare type PagePanelRefs<Slots extends readonly PageSlot[]> = {
 
 export declare type PageRef = ContributionRef<"page">;
 
+declare interface PageResourceCodec {
+    normalize(resource: ResourceRef): ResourceRef;
+    toUri(resource: ResourceRef): string;
+    fromUri(uri: string): ResourceRef | undefined;
+}
+
 /** A page-owned panel. Main presentation and routed context belong to the page. */
 export declare interface PageSlot extends PlacementPresentation {
     readonly id: string;
@@ -2049,6 +2067,12 @@ export declare type PageSlotRegion = ExtensionPanelRegion;
 
 export declare type PageSlotRole = "primary" | "auxiliary";
 
+export declare interface PageUrlDefinition {
+    id: string;
+    ref: PageRef;
+    path: string;
+}
+
 export declare type PanelRef = PlacementRef | PageSlotRef;
 
 declare type ParamBase<TValue, TRequired extends boolean | undefined = boolean | undefined> = {
@@ -2134,6 +2158,26 @@ export declare type ParamType = "text" | "longtext" | "markdown" | "number" | "b
 
 export declare type ParamValue<TDescriptor extends ParamDescriptor> = TDescriptor extends ParamDescriptor<infer V> ? V : never;
 
+export declare interface ParsedWorkbenchPageUrl {
+    pageId: string;
+    resource?: ResourceRef;
+    section?: FileRendererSectionTarget;
+}
+
+/** Resolve a dashboard URL against the caller's declared pages and project. */
+export declare const parsePageUrl: (input: {
+    url: string;
+    projectId: string;
+    pages: readonly PageUrlDefinition[];
+}) => ParsedWorkbenchPageUrl | undefined;
+
+export declare const parseWorkbenchPageUrl: (input: {
+    url: string;
+    projectId: string;
+    pages: readonly PageUrlDefinition[];
+    resources: PageResourceCodec;
+}) => ParsedWorkbenchPageUrl | undefined;
+
 export declare type PatchPart = {
     type: "patch";
     hash?: string;
@@ -2395,6 +2439,9 @@ declare type RequiredParamKeys<TSchema extends ParamObjectSchema> = {
     } ? K : never;
 }[keyof TSchema];
 
+/** Resolve an event ref using the same ownership rules as commands and hooks. */
+export declare const resolveEventReferenceId: (ref: RendererEventReference, ownerExtensionId?: string) => string;
+
 export declare interface ResourceAnchor extends ResourceRef {
     role?: ResourceRole;
 }
@@ -2507,6 +2554,8 @@ export declare type ScheduleExpression = string;
 
 declare type SchemaParams<TSchema extends ParamObjectSchema | undefined> = TSchema extends ParamObjectSchema ? ParamsOf<TSchema> : Record<string, never>;
 
+export declare const SDK_VERSION: string;
+
 /** Mutually-exclusive mode control rendered as a segmented button group. */
 export declare interface SegmentedControl extends BaseControl {
     type: "segmented";
@@ -2576,6 +2625,20 @@ export declare interface SerializedError {
     cause?: JsonValue;
 }
 
+/** Serialize a project page using the same resource encoding as the dashboard. */
+export declare const serializePageUrl: (input: {
+    projectId: string;
+    page: PageUrlDefinition;
+    resource?: ResourceRef;
+}) => string;
+
+export declare const serializeWorkbenchPageUrl: (input: {
+    projectId: string;
+    location: PageLocation;
+    pages: readonly PageUrlDefinition[];
+    resources: PageResourceCodec;
+}) => string;
+
 declare type SessionAttachmentRef = z.infer<typeof sessionAttachmentRefSchema>;
 
 declare const sessionAttachmentRefSchema: z.ZodObject<{
@@ -3214,6 +3277,7 @@ export declare type WebviewCapabilityDeclaration = WebviewDeclarableCapability |
 export declare type WebviewClient<TCommands, TSettings = undefined> = {
     artifacts: WebviewArtifactsClient;
     commands: WebviewCommandsClient<TCommands>;
+    events: WebviewEventsClient;
     settings: WebviewSettingsClient<ClientSettingsMap<TSettings>>;
 };
 
@@ -3242,6 +3306,18 @@ export declare interface WebviewContribution {
 
 export declare type WebviewDeclarableCapability = (typeof WEBVIEW_DECLARABLE_CAPABILITIES)[number];
 
+export declare interface WebviewEventsClient {
+    /** Refetch on a matching event or host sync reconnect. Returns the unsubscribe function. */
+    subscribe(event: RendererEventReference, listener: () => void): () => void;
+}
+
+export declare type WebviewExtensionEvent = {
+    type: "changed";
+    id: string;
+} | {
+    type: "reset";
+};
+
 export declare interface WebviewExtensionSettingKeyParams {
     key: string;
 }

package/dist/hooks.d.ts

@@ -1465,6 +1465,7 @@ declare type SseEvent = {
 };
 
 declare type StartSyncInput = SyncWriterProvider & {
+    /** Called after the initial snapshot, or when a cursor-based connection resumes. */
     onConnected?: () => void;
     onDisconnected?: () => void;
     onConnectionLost?: () => void;

package/package.json

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