@kehto/paja 0.19.0 → 0.20.0

package/dist/index.d.ts

@@ -3,9 +3,9 @@ export { D as DEFAULT_PAJA_AGGREGATE_HASH, c as DEFAULT_PAJA_DTAG, d as DEFAULT_
 import { NostrEvent } from 'nostr-tools';
 import { Filter } from 'nostr-tools/filter';
 import { ResolvedNapplet } from '@kehto/nip/5d';
-import { ShellCapabilities } from '@kehto/shell';
+import { ShellCapabilities, NormalizedIntentUri } from '@kehto/shell';
 export { NappletCspDirective, NappletCspDirectives, NappletCspOptions } from '@kehto/shell';
-import { IntentCatalogEntry, IntentTargetController, IntentDispatchParams, IntentTargetDispatch } from '@kehto/services';
+import { IntentCatalogEntry, IntentTargetController, IntentDispatchParams, IntentTargetAcceptance } from '@kehto/services';
 
 /**
  * Load a JSON Paja config file from disk.
@@ -297,7 +297,9 @@ declare function findRelativeAssetReferences(html: string): string[];
 
 /** Serializable verified pointer and manifest facts for one installed napplet. */
 interface InstalledNappletRecord {
-    /** Verified manifest d-tag used as the handler identity. */
+    /** Publisher/kind-safe verified catalog identity used as the handler identity. */
+    readonly id: string;
+    /** Literal manifest d-tag retained only as artifact metadata. */
     readonly dTag: string;
     /** Verified NIP-5A aggregate hash for the installed artifact. */
     readonly aggregateHash: string;
@@ -313,10 +315,11 @@ interface InstalledNappletRecord {
     readonly archetypes: readonly {
         readonly slug: string;
         readonly convention: string;
+        readonly params: readonly string[];
     }[];
 }
 /** Listener notified when an installed artifact is inserted or removed. */
-type InstalledNappletCatalogListener = (dTag: string) => void;
+type InstalledNappletCatalogListener = (id: string) => void;
 /**
  * Stores verified Paja installations separately from the browser runtime.
  *
@@ -333,19 +336,19 @@ declare class InstalledNappletCatalog {
     /** Insert or replace a record from an already resolver-verified pointer. */
     install(resolved: PajaResolvedPointer): InstalledNappletRecord;
     /** Remove an artifact explicitly; frame teardown never calls this method. */
-    remove(dTag: string): boolean;
-    /** Return whether a verified installation exists for a d-tag. */
-    has(dTag: string): boolean;
+    remove(id: string): boolean;
+    /** Return whether a verified installation exists for a catalog ID. */
+    has(id: string): boolean;
     /** Return immutable serializable installed-artifact facts. */
     installed(): readonly InstalledNappletRecord[];
-    /** Return a verified record by d-tag. */
-    get(dTag: string): InstalledNappletRecord | undefined;
+    /** Return a verified record by catalog ID. */
+    get(id: string): InstalledNappletRecord | undefined;
     /**
      * Atomically confirm that a resolved target still belongs to the exact record
      * selected before an async operation. The record object is the catalog version
      * token, so even a same-identity replacement cannot pass this check.
      */
-    validateCurrent(selected: InstalledNappletRecord, target: Pick<InstalledNappletRecord, 'dTag' | 'aggregateHash'>): InstalledNappletRecord | null;
+    validateCurrent(selected: InstalledNappletRecord, target: Pick<InstalledNappletRecord, 'id' | 'aggregateHash'>): InstalledNappletRecord | null;
     /**
      * Return declared handlers whose host environment can receive intent delivery.
      * @param canReceiveIntent - Resolve intent availability for each verified identity;
@@ -384,14 +387,18 @@ interface BrowserIntentControllerOptions {
     waitForReady(generation: BrowserIntentGeneration): void | Promise<void>;
     /** Return true only while the generation remains the selected current target. */
     isCurrent(generation: BrowserIntentGeneration): boolean | Promise<boolean>;
-    /** Return the runtime-assigned window identifier once the target is ready. */
-    getWindowId(generation: BrowserIntentGeneration): string | null;
+    /** Deprecated target identity probe retained for adapter test compatibility. */
+    getWindowId?(generation: BrowserIntentGeneration): string | null;
     /** Send the convention through the ordinary carrier to the ready generation. */
     send(generation: BrowserIntentGeneration, params: IntentDispatchParams): void | Promise<void>;
     /** Maximum open/replacement attempts. Finite values clamp to 1–10; defaults to two. */
     maxAttempts?: number;
     /** Observe terminal target policy. */
     onTerminal?(params: IntentDispatchParams, reason: BrowserIntentTerminalReason): void;
+    /** Observe successful terminal delivery without adding a second source result. */
+    onDelivered?(params: IntentDispatchParams): void;
+    /** Observe retained target work before its asynchronous completion can race. */
+    onAccepted?(params: IntentDispatchParams, acceptance: IntentTargetAcceptance): void;
 }
 /**
  * Creates/focuses a target and enqueues one convention delivery.
@@ -400,8 +407,75 @@ declare class BrowserIntentController implements IntentTargetController {
     private readonly options;
     private readonly maxAttempts;
     constructor(options: BrowserIntentControllerOptions);
-    dispatch(params: IntentDispatchParams): Promise<IntentTargetDispatch>;
+    /** Retain delivery work immediately; completion remains host-observable only. */
+    accept(params: IntentDispatchParams): IntentTargetAcceptance;
+    /** Complete an already accepted delivery. Kept public for host diagnostics and tests. */
+    dispatch(params: IntentDispatchParams): Promise<void>;
+}
+
+/** Input used to create a Paja intent deep link. */
+interface PajaIntentLinkDescriptor {
+    /** Complete convention URI, including its own query or recommendation fragment. */
+    readonly uri: string;
+    /** Optional Paja target pointer. */
+    readonly pointer?: string;
+    /** Explicit JSON payload kept outside the convention URI. */
+    readonly payload?: unknown;
+}
+/** A validated Paja intent deep link. */
+interface ParsedPajaIntentLink extends PajaIntentLinkDescriptor {
+    /** Canonical request produced from the URI and optional explicit payload. */
+    readonly request: NormalizedIntentUri;
+}
+/**
+ * Parse a Paja intent deep link without invoking it.
+ *
+ * Pointer-only links intentionally return `null` so existing runtime-pointer
+ * startup remains unchanged.
+ *
+ * @param href - Browser location to inspect.
+ * @returns A validated descriptor, or `null` when no intent parameter exists.
+ * @example
+ * ```ts
+ * parsePajaIntentLink('https://paja.example/?intent=napplet%3Anote%2Fopen');
+ * ```
+ */
+declare function parsePajaIntentLink(href: string): ParsedPajaIntentLink | null;
+/**
+ * Create a canonical Paja intent deep link without invoking it.
+ *
+ * @param descriptor - Convention URI, optional pointer, and optional JSON payload.
+ * @param href - Absolute Paja URL to use as the link base.
+ * @returns A canonical intent URL.
+ * @example
+ * ```ts
+ * createPajaIntentLink({ uri: 'napplet:note/open' }, 'https://paja.example/');
+ * ```
+ */
+declare function createPajaIntentLink(descriptor: PajaIntentLinkDescriptor, href: string): string;
+
+/**
+ * Verified, ephemeral source for Paja deep-link intent invocation.
+ *
+ * The launcher event and artifact are static publish-time data.  The signing key
+ * used to create the event is deliberately not present in this repository; a
+ * link's URI and payload travel only over the parent-bound launcher channel.
+ */
+
+/** One parent-to-launcher message; it is deliberately outside signed artifact bytes. */
+interface PajaIntentLauncherMessage {
+    readonly type: 'paja.intent.launch';
+    readonly correlation: string;
+    readonly uri: string;
+    readonly options?: {
+        readonly payload?: unknown;
+        readonly handler?: string;
+    };
 }
+/** Verify the bundled signed manifest and content-addressed launcher bytes. */
+declare function resolvePajaIntentLauncher(): Promise<PajaResolvedPointer>;
+/** Send a reviewed URI only to the frame registered for this launcher generation. */
+declare function postPajaIntentLauncherMessage(frame: Pick<HTMLIFrameElement, 'contentWindow'>, message: PajaIntentLauncherMessage): void;
 
 /**
  * Target dev-server CORS diagnostics.
@@ -471,4 +545,4 @@ type PajaTargetCorsFetch = (input: string, init: {
  */
 declare function probeTargetCors(targetUrl: string, fetchImpl?: PajaTargetCorsFetch): Promise<PajaTargetCorsDiagnostic>;
 
-export { BrowserIntentController, type BrowserIntentControllerOptions, type BrowserIntentGeneration, type BrowserIntentTerminalReason, InstalledNappletCatalog, type InstalledNappletCatalogListener, type InstalledNappletRecord, PAJA_ADVERTISED_DOMAINS, PAJA_COMPATIBILITY_ALIASES, PAJA_HANDSHAKE_DOMAINS, PAJA_LOCAL_SINGLE_FILE_HINT, PAJA_NAPPLET_MANIFEST_KIND, PAJA_NAPPLET_MANIFEST_KINDS, PAJA_REQUIRED_SERVICES, PAJA_TARGET_CORS_HINT, PAJA_UPSTREAM_WEB_DOMAINS, type PajaDecodedPointer, PajaHostConfig, type PajaLocalFileInput, type PajaLocalTarget, type PajaPointerRelayPool, PajaRawOptions, type PajaResolvedPointer, type PajaRuntimeTarget, type PajaTargetCorsDiagnostic, type PajaTargetCorsFetch, type PajaTargetCorsStatus, type ResolvePajaPointerOptions, classifyTargetCors, createPajaLocalTarget, decodePajaPointer, findRelativeAssetReferences, getMissingAdvertisedDomains, getMissingServices, injectPajaRuntimeCsp, isPajaLocalHtmlFile, isPajaLocalTarget, loadPajaConfigFile, mergePajaRawOptions, probeTargetCors, readNappletIdMeta, renderPajaHtml, resolvePajaPointer, resolvePajaRawOptions };
+export { BrowserIntentController, type BrowserIntentControllerOptions, type BrowserIntentGeneration, type BrowserIntentTerminalReason, InstalledNappletCatalog, type InstalledNappletCatalogListener, type InstalledNappletRecord, PAJA_ADVERTISED_DOMAINS, PAJA_COMPATIBILITY_ALIASES, PAJA_HANDSHAKE_DOMAINS, PAJA_LOCAL_SINGLE_FILE_HINT, PAJA_NAPPLET_MANIFEST_KIND, PAJA_NAPPLET_MANIFEST_KINDS, PAJA_REQUIRED_SERVICES, PAJA_TARGET_CORS_HINT, PAJA_UPSTREAM_WEB_DOMAINS, type PajaDecodedPointer, PajaHostConfig, type PajaIntentLauncherMessage, type PajaIntentLinkDescriptor, type PajaLocalFileInput, type PajaLocalTarget, type PajaPointerRelayPool, PajaRawOptions, type PajaResolvedPointer, type PajaRuntimeTarget, type PajaTargetCorsDiagnostic, type PajaTargetCorsFetch, type PajaTargetCorsStatus, type ParsedPajaIntentLink, type ResolvePajaPointerOptions, classifyTargetCors, createPajaIntentLink, createPajaLocalTarget, decodePajaPointer, findRelativeAssetReferences, getMissingAdvertisedDomains, getMissingServices, injectPajaRuntimeCsp, isPajaLocalHtmlFile, isPajaLocalTarget, loadPajaConfigFile, mergePajaRawOptions, parsePajaIntentLink, postPajaIntentLauncherMessage, probeTargetCors, readNappletIdMeta, renderPajaHtml, resolvePajaIntentLauncher, resolvePajaPointer, resolvePajaRawOptions };

package/dist/index.js

@@ -23,6 +23,7 @@ import {
   ReadinessError,
   classifyTargetCors,
   createPajaHostConfig,
+  createPajaIntentLink,
   createPajaLocalTarget,
   createPajaRuntimeHostConfig,
   decodePajaPointer,
@@ -37,15 +38,18 @@ import {
   mergePajaRawOptions,
   normalizePajaOptions,
   normalizePajaSimulation,
+  parsePajaIntentLink,
+  postPajaIntentLauncherMessage,
   probeTargetCors,
   readNappletIdMeta,
   renderPajaHtml,
+  resolvePajaIntentLauncher,
   resolvePajaPointer,
   resolvePajaRawOptions,
   startPajaServer,
   summarizePajaSimulation,
   waitForTargetUrl
-} from "./chunk-GY5ET3PC.js";
+} from "./chunk-6WEO5D3Z.js";
 export {
   BrowserIntentController,
   DEFAULT_PAJA_AGGREGATE_HASH,
@@ -71,6 +75,7 @@ export {
   ReadinessError,
   classifyTargetCors,
   createPajaHostConfig,
+  createPajaIntentLink,
   createPajaLocalTarget,
   createPajaRuntimeHostConfig,
   decodePajaPointer,
@@ -85,9 +90,12 @@ export {
   mergePajaRawOptions,
   normalizePajaOptions,
   normalizePajaSimulation,
+  parsePajaIntentLink,
+  postPajaIntentLauncherMessage,
   probeTargetCors,
   readNappletIdMeta,
   renderPajaHtml,
+  resolvePajaIntentLauncher,
   resolvePajaPointer,
   resolvePajaRawOptions,
   startPajaServer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kehto/paja",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Paja local authoring workshop for hosting napplets in a real Kehto iframe during development",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,13 +25,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@kehto/acl": "^0.19.0",
-    "@kehto/nip": "^0.6.0",
     "@kehto/firewall": "^0.6.0",
+    "@kehto/acl": "^0.19.0",
+    "@kehto/nip": "^0.7.0",
     "@kehto/runtime": "^0.24.0",
-    "@kehto/services": "^0.22.1",
-    "@kehto/wm": "^0.0.2",
-    "@kehto/shell": "^0.22.0"
+    "@kehto/services": "^0.23.0",
+    "@kehto/shell": "^0.23.0",
+    "@kehto/wm": "^0.0.2"
   },
   "peerDependencies": {
     "@napplet/core": ">=0.32.0 <0.33.0",