@napplet/conformance-cli 0.3.4 → 0.4.1

package/dist/host-bundle.global.js

@@ -1,7 +1,7 @@
 "use strict";
 var NappletConformanceHostBundle = (() => {
   // ../core/dist/index.js
-  var NAP_DOMAINS = ["shell", "relay", "identity", "storage", "inc", "theme", "keys", "media", "notify", "config", "resource", "cvm", "outbox", "upload", "intent", "ble", "webrtc", "link", "count", "lists", "serial", "fs", "common", "dm", "gamepad"];
+  var NAP_DOMAINS = ["shell", "relay", "identity", "storage", "inc", "theme", "keys", "media", "notify", "config", "resource", "cvm", "outbox", "upload", "intent", "ble", "webrtc", "link", "count", "lists", "serial", "fs", "common", "dm", "gamepad", "llm"];
   function createDispatch() {
     const handlers = /* @__PURE__ */ new Map();
     function registerNap2(domain, handler) {
@@ -10,13 +10,13 @@ var NappletConformanceHostBundle = (() => {
       }
       handlers.set(domain, handler);
     }
-    function dispatch2(message) {
-      const dotIndex = message.type.indexOf(".");
+    function dispatch2(message2) {
+      const dotIndex = message2.type.indexOf(".");
       if (dotIndex <= 0) return false;
-      const domain = message.type.slice(0, dotIndex);
+      const domain = message2.type.slice(0, dotIndex);
       const handler = handlers.get(domain);
       if (!handler) return false;
-      handler(message);
+      handler(message2);
       return true;
     }
     function getRegisteredDomains2() {
@@ -32,6 +32,17 @@ var NappletConformanceHostBundle = (() => {
   // ../conformance/dist/index.js
   var ID = { id: "string" };
   var ENVELOPE_SPECS = {
+    // NAP-LLM Wire Protocol: four request/result pairs plus the unsolicited delta.
+    // https://github.com/napplet/naps/pull/134
+    "llm.select": { dir: "out", fields: { ...ID } },
+    "llm.select.result": { dir: "in", fields: { ...ID } },
+    "llm.describe": { dir: "out", fields: { ...ID, handle: "string" } },
+    "llm.describe.result": { dir: "in", fields: { ...ID } },
+    "llm.generate": { dir: "out", fields: { ...ID, request: "object" } },
+    "llm.generate.result": { dir: "in", fields: { ...ID } },
+    "llm.delta": { dir: "in", fields: { requestId: "string", sequence: "number", text: "string" } },
+    "llm.cancel": { dir: "out", fields: { ...ID, requestId: "string" } },
+    "llm.cancel.result": { dir: "in", fields: { ...ID } },
     // NAP-GAMEPAD Wire Protocol: all three messages are fire-and-forget, without ids.
     // https://github.com/napplet/naps/pull/108
     "gamepad.subscribe": { dir: "out", forbiddenFields: ["id"], forbiddenReason: "NAP-GAMEPAD fire-and-forget envelopes do not carry it" },
@@ -305,6 +316,59 @@ var NappletConformanceHostBundle = (() => {
     "dm.unsubscribe.result": { dir: "in" },
     "dm.message": { dir: "in" }
   };
+  var text = (value) => typeof value === "string";
+  var nonemptyText = (value) => typeof value === "string" && value.length > 0;
+  var boolean = (value) => typeof value === "boolean";
+  var oneOf = (...allowed) => (value) => typeof value === "string" && allowed.includes(value);
+  var base64 = (value) => typeof value === "string" && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value) && value.length >= 4;
+  function exactRecord(required, optional = {}) {
+    return (value) => {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+      const data = value;
+      if (Object.keys(data).some((key) => !(key in required) && !(key in optional))) return false;
+      return Object.entries(required).every(([key, check]) => check(data[key])) && Object.entries(optional).every(([key, check]) => data[key] === void 0 || check(data[key]));
+    };
+  }
+  var nonemptyList = (item) => (value) => Array.isArray(value) && value.length > 0 && value.every(item);
+  var textPart = exactRecord({ type: oneOf("text"), text });
+  var imagePart = exactRecord({ type: oneOf("image"), mimeType: oneOf("image/png", "image/jpeg", "image/webp"), data: base64 });
+  var part = (value) => textPart(value) || imagePart(value);
+  var message = exactRecord({ role: oneOf("system", "user", "assistant"), content: nonemptyList(part) });
+  var requirements = exactRecord({}, { model: nonemptyText, images: boolean, json: boolean });
+  var generationRequest = exactRecord({ handle: nonemptyText, messages: nonemptyList(message) }, { format: oneOf("text", "json") });
+  var PAYLOADS = {
+    "llm.select": { optional: { requirements } },
+    "llm.describe": { required: { handle: nonemptyText } },
+    "llm.generate": { required: { request: generationRequest } },
+    "llm.cancel": { required: { requestId: nonemptyText } }
+  };
+  function validateLlmRequest(type, envelope, errors) {
+    const schema = PAYLOADS[type];
+    if (!schema) return;
+    const required = schema.required ?? {};
+    const optional = schema.optional ?? {};
+    if (envelope.id !== void 0 && !nonemptyText(envelope.id)) {
+      errors.push({ code: "wrong-type", field: "id", message: "NAP-LLM request ids are non-empty text" });
+    }
+    for (const field of Object.keys(envelope)) {
+      if (field === "type" || field === "id" || field in required || field in optional) continue;
+      errors.push({
+        code: "forbidden-field",
+        field,
+        message: `Field "${field}" is not a parameter of ${type}; NAP-LLM requests carry exactly their API row parameters`
+      });
+    }
+    for (const [field, check] of Object.entries({ ...required, ...optional })) {
+      const value = envelope[field];
+      if (value === void 0) {
+        if (field in required) errors.push({ code: "missing-field", field, message: `Field "${field}" is required by ${type}` });
+        continue;
+      }
+      if (!check(value)) {
+        errors.push({ code: "wrong-type", field, message: `Field "${field}" must match the NAP-LLM ${type} schema` });
+      }
+    }
+  }
   function kindOf(value) {
     if (value === void 0) return "undefined";
     if (value === null) return "null";
@@ -415,12 +479,12 @@ var NappletConformanceHostBundle = (() => {
       if (entry.servers !== void 0) validateServerHints(entry.servers, `${field}.servers`, errors);
     }
   }
-  function validateEnvelope(message) {
+  function validateEnvelope(message2) {
     const errors = [];
-    if (typeof message !== "object" || message === null || Array.isArray(message)) {
+    if (typeof message2 !== "object" || message2 === null || Array.isArray(message2)) {
       return { ok: false, errors: [{ code: "not-an-object", message: "Envelope must be a non-null object" }] };
     }
-    const record = message;
+    const record = message2;
     const type = record["type"];
     if (typeof type !== "string") {
       return { ok: false, errors: [{ code: "missing-type", message: "Envelope is missing a string `type` field" }] };
@@ -472,6 +536,7 @@ var NappletConformanceHostBundle = (() => {
         });
       }
     }
+    if (domain === "llm") validateLlmRequest(type, record, errors);
     if (type === "intent.invoke") {
       validateIntentInvokeRequest(record.request, errors);
     }
@@ -491,6 +556,8 @@ var NappletConformanceHostBundle = (() => {
     NAPPLET_KIND_ROOT,
     NAPPLET_KIND_NAMED
   ];
+  var SCREENSHOT_FORMATS = ["image/png", "image/jpeg", "image/webp"];
+  var MIME_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i;
   function firstTag(event, name) {
     return event.tags.find((tag) => tag[0] === name);
   }
@@ -507,6 +574,71 @@ var NappletConformanceHostBundle = (() => {
   function manifestRequires(event) {
     return event.tags.filter((tag) => tag[0] === "R").map((tag) => tag[1]?.trim() ?? "").filter(Boolean);
   }
+  function parsePresentationMedia(event) {
+    const warnings = [];
+    const screenshots = [];
+    for (const tag of event.tags.filter((tag2) => tag2[0] === "screenshot")) {
+      const media = parseMediaTag(tag, warnings);
+      if (media) screenshots.push(media);
+    }
+    const previews = event.tags.filter((tag) => tag[0] === "preview");
+    let preview;
+    if (previews.length > 1) {
+      warnings.push({ code: "invalid-presentation-media", message: "Multiple preview tags; clients ignore the preview (NIP-5D \xA7Presentation media)" });
+    } else if (previews.length === 1) {
+      preview = parseMediaTag(previews[0], warnings);
+    }
+    return { screenshots, preview, warnings };
+  }
+  function parseMediaTag(tag, warnings) {
+    const name = tag[0];
+    const ignore = (reason) => {
+      warnings.push({ code: "invalid-presentation-media", message: `Ignore ${name} tag: ${reason} (NIP-5D \xA7Presentation media)` });
+      return void 0;
+    };
+    const fields = /* @__PURE__ */ new Map();
+    for (const field of tag.slice(1)) {
+      const space = typeof field === "string" ? field.indexOf(" ") : -1;
+      const key = space < 0 ? field : field.slice(0, space);
+      const value = space < 0 ? void 0 : field.slice(space + 1);
+      const values = fields.get(key) ?? [];
+      if (value !== void 0) values.push(value);
+      else values.push("");
+      fields.set(key, values);
+    }
+    const hashes = fields.get("x");
+    if (!hashes || hashes.length !== 1 || !isSha256Hex(hashes[0])) return ignore("exactly one x field with a lowercase sha256 is required");
+    const media = { sha256: hashes[0] };
+    const optional = (key, accept) => {
+      const values = fields.get(key);
+      if (!values) return void 0;
+      if (values.length !== 1 || !accept(values[0])) {
+        warnings.push({ code: "invalid-presentation-media", message: `Ignore ${key} field on ${name} ${media.sha256}: malformed or repeated (NIP-5D \xA7Presentation media)` });
+        return void 0;
+      }
+      return values[0];
+    };
+    const mimeType = optional("m", (value) => MIME_TYPE.test(value));
+    if (mimeType !== void 0) {
+      const decodable = name === "preview" ? mimeType.toLowerCase().startsWith("video/") : SCREENSHOT_FORMATS.includes(mimeType.toLowerCase());
+      if (!decodable) return ignore(`${mimeType} cannot match a decodable ${name === "preview" ? "video" : "PNG, JPEG or WebP"} format`);
+      media.mimeType = mimeType;
+    }
+    const dim = optional("dim", (value) => /^[1-9][0-9]*x[1-9][0-9]*$/.test(value));
+    if (dim !== void 0) {
+      const [width, height] = dim.split("x").map(Number);
+      media.dim = { width, height };
+    }
+    const size = optional("size", (value) => /^(?:0|[1-9][0-9]*)$/.test(value));
+    if (size !== void 0) media.size = Number(size);
+    if (name === "preview") {
+      const duration = optional("duration", (value) => /^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(value));
+      if (duration !== void 0) media.duration = Number(duration);
+    }
+    const alt = optional("alt", (value) => value.trim().length > 0);
+    if (alt !== void 0) media.alt = alt;
+    return media;
+  }
   function validateManifestEvent(event) {
     const errors = [];
     const warnings = [];
@@ -569,15 +701,55 @@ var NappletConformanceHostBundle = (() => {
         errors.push({ code: "invalid-metadata", message: `Invalid ${name} tag cardinality for kind ${event.kind}` });
       }
     }
+    const sources = event.tags.filter((tag) => tag[0] === "source");
+    for (const tag of sources) {
+      if (tag.length !== 2 || !isSourceLocation(tag[1])) {
+        errors.push({ code: "invalid-metadata", message: "source must contain one HTTP(S), SSH, Git, SCP, or nostr repository location" });
+      }
+    }
+    validateSourcePins(event, sources.length === 1 && sources[0].length === 2 && isSourceLocation(sources[0][1]), errors, warnings);
     for (const tag of event.tags.filter((tag2) => tag2[0] === "i")) {
       if (!tag[1]?.trim() || tag[1].includes("?")) {
         errors.push({ code: "invalid-metadata", message: "Intent advertisements must be non-empty queryless identities" });
       }
     }
     const icons = event.tags.filter((tag) => tag[0] === "icon");
-    if (icons.length > 1 || icons.some((tag) => tag.length !== 3 || !isSha256Hex(tag[1]) || !["image/png", "image/jpeg", "image/webp"].includes(tag[2]))) {
+    if (icons.length > 1 || icons.some((tag) => tag.length !== 3 || !isSha256Hex(tag[1]) || !SCREENSHOT_FORMATS.includes(tag[2]))) {
       warnings.push({ code: "invalid-icon", message: "Ignore invalid icon metadata and use generic artwork (NIP-5D \xA7Icon)" });
     }
+    warnings.push(...parsePresentationMedia(event).warnings);
+  }
+  function validateSourcePins(event, hasRepositorySource, errors, warnings) {
+    const commits = event.tags.filter((tag) => tag[0] === "source-commit");
+    if (commits.length > 1 || commits.some((tag) => tag.length !== 2 || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(tag[1]))) {
+      errors.push({ code: "invalid-metadata", message: "source-commit must appear once with a full lowercase-hex Git commit ID (40 or 64 characters)" });
+    } else if (commits.length === 1 && !hasRepositorySource) {
+      warnings.push({ code: "unused-source-commit", message: "source-commit without a Git repository source is ignored (NIP-5D \xA7Source)" });
+    }
+    const archives = event.tags.filter((tag) => tag[0] === "source-archive");
+    if (archives.length > 1 || archives.some((tag) => tag.length !== 4 || !isArchiveUrl(tag[1]) || !isSha256Hex(tag[2]) || !MIME_TYPE.test(tag[3] ?? ""))) {
+      errors.push({ code: "invalid-metadata", message: "source-archive must appear once with an HTTPS URL without credentials or fragment, a lowercase sha256, and a MIME type" });
+    }
+  }
+  function isArchiveUrl(value) {
+    if (!value || value.includes("#")) return false;
+    try {
+      const url = new URL(value);
+      return url.protocol === "https:" && !url.username && !url.password;
+    } catch {
+      return false;
+    }
+  }
+  function isSourceLocation(value) {
+    if (!value || /^[a-z]:[\\/]/i.test(value)) return false;
+    try {
+      const { protocol } = new URL(value);
+      if (["http:", "https:", "ssh:", "git:"].includes(protocol)) return true;
+      if (protocol === "nostr:") return value.length > "nostr://".length && value.startsWith("nostr://");
+      if (protocol === "file:") return false;
+    } catch {
+    }
+    return !value.includes("://") && /^(?:[^@\s/:]+@)?[^:\s/]+:[^\s]+$/.test(value);
   }
   var REFERENCE_PUBKEY = "f".repeat(64);
   var REFERENCE_ENDPOINT = { id: "reference-source-endpoint", catalogId: "reference-source" };
@@ -600,10 +772,10 @@ var NappletConformanceHostBundle = (() => {
     const meta = url.slice("data:".length, comma);
     const body = url.slice(comma + 1);
     const parts = meta.split(";").filter(Boolean);
-    const base64 = parts.includes("base64");
-    const mime = parts.find((part) => part.includes("/")) ?? "text/plain";
+    const base642 = parts.includes("base64");
+    const mime = parts.find((part2) => part2.includes("/")) ?? "text/plain";
     try {
-      if (base64) {
+      if (base642) {
         const binary = globalThis.atob(body);
         const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
         return { blob: new Blob([bytes], { type: mime }), mime };
@@ -835,9 +1007,111 @@ var NappletConformanceHostBundle = (() => {
     "fs.watch": (e) => ok({ type: "fs.watch.result", id: e.id, watchId: `watch-${String(e.id)}` }),
     "fs.unwatch": (e) => ok({ type: "fs.unwatch.result", id: e.id })
   };
+  var REFERENCE_LLM_CONNECTION = {
+    name: "Reference connection",
+    model: "reference-model",
+    route: "Reference shell \u2192 reference provider (no network)",
+    images: true,
+    json: true
+  };
+  var fail = (code, message2) => ({ error: { code, message: message2 } });
+  var object = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+  function sessionFor(sessions, endpoint) {
+    let session = sessions.get(endpoint.id);
+    if (!session) {
+      session = { handles: /* @__PURE__ */ new Set(), active: /* @__PURE__ */ new Map(), sequence: 0 };
+      sessions.set(endpoint.id, session);
+    }
+    return session;
+  }
+  function modelFor(handle2) {
+    return { handle: handle2, ...REFERENCE_LLM_CONNECTION };
+  }
+  function select(session, envelope) {
+    const requirements2 = object(envelope.requirements);
+    if (requirements2.model !== void 0 && requirements2.model !== REFERENCE_LLM_CONNECTION.model) {
+      return fail("unsupported", "No connection offers the requested model");
+    }
+    session.sequence += 1;
+    const handle2 = `reference-llm-h${session.sequence}`;
+    session.handles.add(handle2);
+    return { model: modelFor(handle2) };
+  }
+  function describe(session, envelope) {
+    const handle2 = String(envelope.handle);
+    if (!session.handles.has(handle2)) return fail("selection-expired", "Select a model again");
+    return { model: modelFor(handle2) };
+  }
+  function lastUserText(request) {
+    const messages = Array.isArray(request.messages) ? request.messages : [];
+    let text2 = "";
+    for (const message2 of messages) {
+      const record = object(message2);
+      if (record.role !== "user" || !Array.isArray(record.content)) continue;
+      for (const part2 of record.content) {
+        const item = object(part2);
+        if (item.type === "text" && typeof item.text === "string") text2 = item.text;
+      }
+    }
+    return text2;
+  }
+  function generate(session, id, envelope) {
+    const reply = (outcome) => [{ type: "llm.generate.result", id, ...outcome }];
+    if (session.active.has(id)) return reply(fail("invalid-request", "Request id is still active"));
+    const request = object(envelope.request);
+    if (!session.handles.has(String(request.handle))) return reply(fail("selection-expired", "Select a model again"));
+    const prompt = lastUserText(request);
+    if (prompt.includes("[[decline]]")) return reply(fail("user-cancelled", "The user declined disclosure"));
+    if (prompt.includes("[[stall]]")) {
+      session.active.set(id, envelope);
+      return [];
+    }
+    if (prompt.includes("[[refuse]]")) return reply({ result: { text: "", finish: "refusal" } });
+    const output = request.format === "json" ? JSON.stringify({ echo: prompt }) : `Echo: ${prompt}`;
+    const usage = { inputTokens: JSON.stringify(request.messages).length, outputTokens: output.length };
+    return [
+      { type: "llm.delta", requestId: id, sequence: 0, text: output.slice(0, Math.ceil(output.length / 2)) },
+      ...reply({ result: { text: output, finish: "stop", usage } })
+    ];
+  }
+  function cancel(session, id, envelope) {
+    const requestId = String(envelope.requestId);
+    if (!session.active.delete(requestId)) return [{ type: "llm.cancel.result", id, cancelled: false }];
+    return [
+      { type: "llm.generate.result", id: requestId, error: { code: "cancelled", message: "Generation cancelled; provider charges may still apply." } },
+      { type: "llm.cancel.result", id, cancelled: true }
+    ];
+  }
+  function handle(sessions, endpoint, envelope) {
+    const type = String(envelope.type);
+    const id = String(envelope.id);
+    const session = sessionFor(sessions, endpoint);
+    switch (type) {
+      case "llm.select":
+        return [{ type: "llm.select.result", id, ...select(session, envelope) }];
+      case "llm.describe":
+        return [{ type: "llm.describe.result", id, ...describe(session, envelope) }];
+      case "llm.generate":
+        return structuredClone(generate(session, id, envelope));
+      case "llm.cancel":
+        return cancel(session, id, envelope);
+      default:
+        return [{ type: `${type}.result`, id, error: { code: "invalid-request", message: `Unknown operation ${type}` } }];
+    }
+  }
+  function createLlmHandlers() {
+    const sessions = /* @__PURE__ */ new Map();
+    return {
+      handle: (endpoint, envelope) => handle(sessions, endpoint, envelope),
+      reset() {
+        sessions.clear();
+      }
+    };
+  }
   function createReferenceHandler(options) {
     const initialized = /* @__PURE__ */ new Set();
-    return (endpoint, envelope) => {
+    const llm = createLlmHandlers();
+    const handle2 = (endpoint, envelope) => {
       const type = getEnvelopeType(envelope);
       const verdict = validateEnvelope(envelope);
       options.records.push({ envelope, verdict, timestamp: options.now() });
@@ -850,6 +1124,7 @@ var NappletConformanceHostBundle = (() => {
         return ok({ type: "shell.init", capabilities: { domains: [...domains] }, services: [] });
       }
       const env = envelope;
+      if (type.startsWith("llm.")) return llm.handle(endpoint, env);
       if (type === "intent.invoke") return options.intents.handleInvoke(endpoint, env);
       if (type === "intent.available") {
         return ok({ type: "intent.available.result", id: env.id, availability: options.intents.availability(env.archetype) });
@@ -861,6 +1136,9 @@ var NappletConformanceHostBundle = (() => {
       const responder = RESPONDERS[type];
       return responder ? responder(env) : [];
     };
+    return Object.assign(handle2, { reset() {
+      llm.reset();
+    } });
   }
   function getEnvelopeType(envelope) {
     if (!envelope || typeof envelope !== "object") return void 0;
@@ -956,6 +1234,7 @@ var NappletConformanceHostBundle = (() => {
       takeDeliveries: deliveries.take,
       reset() {
         records.length = 0;
+        handleFrom.reset();
         deliveries.clear();
       }
     };
@@ -978,7 +1257,58 @@ var NappletConformanceHostBundle = (() => {
       }
     };
   }
+  var LLM_PRELUDE_SOURCE = `
+  if (domains.includes('llm')) {
+    const llmFields = { 'llm.select.result': 'model', 'llm.describe.result': 'model', 'llm.generate.result': 'result', 'llm.cancel.result': 'cancelled' };
+    const llmDeltas = new Map();
+    window.addEventListener('message', (event) => {
+      if (event.source !== window.parent) return;
+      const msg = event.data;
+      if (!msg || typeof msg !== 'object' || msg.type !== 'llm.delta' || 'id' in msg || typeof msg.requestId !== 'string') return;
+      const entry = llmDeltas.get(msg.requestId);
+      if (!entry || typeof msg.sequence !== 'number' || typeof msg.text !== 'string') return;
+      if (msg.sequence !== entry.next) { entry.next = Infinity; return; }
+      entry.next += 1;
+      if (entry.onDelta) entry.onDelta({ requestId: msg.requestId, sequence: msg.sequence, text: msg.text });
+    });
+    const llmRequest = (payload, id) => {
+      const type = payload.type;
+      return request(id === undefined ? payload : { ...payload, id }, type + '.result').then((message) => {
+        const field = llmFields[message.type];
+        const hasValue = message[field] !== undefined && message[field] !== null;
+        const hasError = message.error !== undefined && message.error !== null;
+        if (hasValue === hasError) throw new Error(type + '.result must carry exactly one of ' + field + ' or error');
+        if (hasError) {
+          const failure = new Error(String(message.error.message));
+          failure.name = 'LlmError';
+          failure.code = message.error.code;
+          throw failure;
+        }
+        return message[field];
+      });
+    };
+    napplet.llm = {
+      select: (requirements) => llmRequest(requirements === undefined ? { type: 'llm.select' } : { type: 'llm.select', requirements }),
+      describe: (handle) => llmRequest({ type: 'llm.describe', handle }),
+      generate: (generation, options) => {
+        const id = nextId();
+        const entry = { next: 0, onDelta: options && options.onDelta };
+        llmDeltas.set(id, entry);
+        const signal = options && options.signal;
+        const abort = () => { napplet.llm.cancel(id).catch(() => undefined); };
+        if (signal) { if (signal.aborted) abort(); else signal.addEventListener('abort', abort, { once: true }); }
+        const pendingGeneration = llmRequest({ type: 'llm.generate', request: generation }, id).finally(() => {
+          llmDeltas.delete(id);
+          if (signal) signal.removeEventListener('abort', abort);
+        });
+        return Object.assign(pendingGeneration, { requestId: id });
+      },
+      cancel: (requestId) => llmRequest({ type: 'llm.cancel', requestId }),
+    };
+  }
+`;
   var INTERNAL_BOOT_ERROR = "__nappletConformance.error";
+  var INTERNAL_INSTALLED = "__nappletConformance.installed";
   function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
@@ -1013,13 +1343,26 @@ var NappletConformanceHostBundle = (() => {
   };
   return { isGamepadState, copyGamepadState };
 })()`;
-  function runtimePrelude(domains) {
-    return `
+  function errorObserver() {
+    return `(() => {
+    const report = (reason) => {
+      try { window.parent.postMessage({ type: '${INTERNAL_BOOT_ERROR}', reason: String(reason && reason.message || reason) }, '*'); }
+      catch {}
+    };
+    window.addEventListener('error', (event) => report(event.error || event.message));
+    window.addEventListener('unhandledrejection', (event) => report(event.reason));
+  })();`;
+  }
+  var FALLBACK_RUNTIME_OPEN = `
 (() => {
-  const domains = ${JSON.stringify(domains)};
+  const domains = `;
+  var FALLBACK_RUNTIME_BEFORE_GAMEPAD_TOOLS = `;
   const napplet = {};
-  for (const domain of domains) napplet[domain] = {};
-  const gamepadTools = ${GAMEPAD_STATE_TOOLS_SOURCE};
+  for (const domain of domains) {
+    if (domain === 'resource' || domain === 'gamepad') napplet[domain] = {};
+  }
+  const gamepadTools = `;
+  var FALLBACK_RUNTIME_AFTER_GAMEPAD_TOOLS = `;
   let gamepadState = { available: true, focused: false, pads: [] };
   const gamepadHandlers = new Set();
   // Subscribe on first use, like the nap binding, so napplets that never touch
@@ -1118,20 +1461,25 @@ var NappletConformanceHostBundle = (() => {
       return handle;
     };
   }
+  ${LLM_PRELUDE_SOURCE}
   window.napplet = napplet;
-  const report = (reason) => {
-    try {
-      window.parent.postMessage({ type: '${INTERNAL_BOOT_ERROR}', reason: String(reason && reason.message || reason) }, '*');
-    } catch {}
-  };
-  window.addEventListener('error', (event) => report(event.error || event.message));
-  window.addEventListener('unhandledrejection', (event) => report(event.reason));
+  `;
+  var FALLBACK_RUNTIME_CLOSE = `
 })();
 `;
+  function runtimePrelude(domains, runtimePreludeSource) {
+    const installed = `window.parent.postMessage({ type: '${INTERNAL_INSTALLED}', installed: !!window.napplet }, '*');`;
+    if (runtimePreludeSource !== void 0) {
+      return `${runtimePreludeSource}
+;globalThis.NappletShimPrelude.install(${JSON.stringify({ domains })});
+${installed}`;
+    }
+    return FALLBACK_RUNTIME_OPEN + JSON.stringify(domains) + FALLBACK_RUNTIME_BEFORE_GAMEPAD_TOOLS + GAMEPAD_STATE_TOOLS_SOURCE + FALLBACK_RUNTIME_AFTER_GAMEPAD_TOOLS + installed + FALLBACK_RUNTIME_CLOSE;
   }
-  function injectRuntime(html, url, domains) {
+  function injectRuntime(html, url, domains, runtimePreludeSource) {
     const base = `<base href="${escapeHtmlAttr(url)}">`;
-    const script = `<script>${runtimePrelude(domains)}<\/script>`;
+    const source = runtimePrelude(domains, runtimePreludeSource).replace(/<\/script/gi, "<\\/script");
+    const script = `<script>${errorObserver()}<\/script><script>${source}<\/script>`;
     const headOpen = /<head(?:\s[^>]*)?>/i.exec(html);
     if (headOpen) {
       const at = headOpen.index + headOpen[0].length;
@@ -1167,9 +1515,14 @@ var NappletConformanceHostBundle = (() => {
     iframe.style.height = "1px";
     iframe.style.left = "-9999px";
     let bootError = null;
+    let installedGlobal = false;
     const listener = (event) => {
       if (event.source !== iframe.contentWindow) return;
       const data = event.data;
+      if (data && typeof data === "object" && data.type === INTERNAL_INSTALLED) {
+        installedGlobal = data.installed === true;
+        return;
+      }
       if (data && typeof data === "object" && data.type === INTERNAL_BOOT_ERROR) {
         bootError = `napplet boot error: ${String(data.reason ?? "unknown error")}`;
         return;
@@ -1186,10 +1539,10 @@ var NappletConformanceHostBundle = (() => {
       }, { once: true });
     });
     win.addEventListener("message", listener);
-    (doc.body ?? doc.documentElement).appendChild(iframe);
     try {
-      const html = await loadHtml(opts.url);
-      iframe.srcdoc = injectRuntime(html, opts.url, domains);
+      const html = opts.html ?? await loadHtml(opts.url);
+      iframe.srcdoc = injectRuntime(html, opts.url, domains, opts.runtimePreludeSource);
+      (doc.body ?? doc.documentElement).appendChild(iframe);
     } catch (error) {
       bootError = error instanceof Error ? error.message : String(error);
     }
@@ -1207,16 +1560,18 @@ var NappletConformanceHostBundle = (() => {
       iframe.remove();
     } catch {
     }
-    return { installedGlobal: bootError === null, bootError, emitted: [...shell.records] };
+    return { installedGlobal, bootError, emitted: [...shell.records] };
   }
   async function bootAndCollect(options) {
     const doc = options.document ?? document;
     const win = options.window ?? window;
     const resolved = {
       url: options.url,
+      html: options.html,
       readyTimeoutMs: options.readyTimeoutMs ?? 5e3,
       settleMs: options.settleMs ?? 600,
-      allowSameOrigin: options.allowSameOrigin ?? false
+      allowSameOrigin: options.allowSameOrigin ?? false,
+      runtimePreludeSource: options.runtimePreludeSource
     };
     const primary = await bootOnce(NAP_DOMAINS, resolved, doc, win);
     let degraded = null;
@@ -1232,9 +1587,9 @@ var NappletConformanceHostBundle = (() => {
     };
   }
   var pass = (detail) => ({ status: "pass", detail });
-  var fail = (detail, diagnostics) => ({ status: "fail", detail, diagnostics });
+  var fail2 = (detail, diagnostics) => ({ status: "fail", detail, diagnostics });
   var skip = (detail) => ({ status: "skip", detail });
-  var result = { pass, fail, skip };
+  var result = { pass, fail: fail2, skip };
   function manifestErrors(ctx, codes) {
     const verdict = validateManifestEvent(ctx.manifestEvent);
     return [...verdict.errors, ...verdict.warnings].filter((e) => codes.includes(e.code));
@@ -1272,6 +1627,12 @@ var NappletConformanceHostBundle = (() => {
     manifestCheck("manifest/requires-known", "R/O domains are in this toolchain registry (advisory)", [
       "unknown-required-nap"
     ], "warning"),
+    // NIP-5D §Icon, §Presentation media and §Source: clients ignore these, never fail.
+    manifestCheck("manifest/media-usable", "Icon, screenshots, preview and source pins are usable (advisory)", [
+      "invalid-icon",
+      "invalid-presentation-media",
+      "unused-source-commit"
+    ], "warning"),
     // ── boot ─────────────────────────────────────────────────────────────────────
     {
       id: "boot/sandbox-allow-scripts",