@jini-ai/agentic 0.1.0

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,gDAAgD;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAuDD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,qBAAqB,GACrB,iBAAiB,CAAC;AAYtB,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;AAEpF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CA0BpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,GAAG,IAAI,CAQhF;AAiBD,0GAA0G;AAC1G,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAElE;AAED,4IAA4I;AAC5I,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAE1E;AAED,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAa1C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAyB,GAAG,eAAe,CAKpG"}

package/dist/guards.js

@@ -0,0 +1,181 @@
+/**
+ * @module guards
+ *
+ * The refusals that must hold on every surface, expressed over plain descriptors rather than
+ * DOM nodes so they are testable in Node and reusable from any framework binding.
+ *
+ * Both guards here answer review findings that an allowlist alone does not cover: a generic
+ * filler will happily type into a password or card-number field even when that field carries a
+ * legitimate handle, and `data-agent-label` is page-authored text that reaches a model as if
+ * the host had written it.
+ */
+/** Input types no automated caller may ever write to. */
+const DENIED_TYPES = new Set(['password', 'hidden', 'file', 'image']);
+/** Autocomplete tokens covering credentials, payment instruments and one-time codes. */
+const DENIED_AUTOCOMPLETE = new Set([
+    'current-password', 'new-password', 'one-time-code',
+    'cc-number', 'cc-exp', 'cc-exp-month', 'cc-exp-year', 'cc-csc', 'cc-name', 'cc-type',
+]);
+/**
+ * Substrings in `name`/`id` that indicate a secret even when type/autocomplete are unset.
+ *
+ * Matched against {@link squashSeparators}'d text, so the multi-word entries catch the separator
+ * spellings people actually use. `api_key`, `api-key` and `apiKey` are all the same field; a
+ * literal-substring match sees only the last one, which is the least common of the three.
+ */
+const SUSPICIOUS_NAME = /(?:password|passwd|secret|token|csrf|xsrf|otp|cvv|cvc|ssn|creditcard|cardnumber|apikey|ccnumber|cardnum|accountnumber|routing|iban|sortcode|securitycode|passphrase|privatekey|clientsecret|accesskey|secretkey|recoverycode|backupcode|mfa)/i;
+// Deliberately NOT added as bare substrings, even though both are real PCI/banking terms
+// ("pin", "PAN" — Primary Account Number): they collide with ordinary field names once
+// separators are squashed out. `shipping` contains "pin"; `company` contains "pan". Adding
+// either here would refuse a large share of legitimate, non-sensitive fields. See
+// guards.test.ts's "does not refuse ordinary fields that happen to contain pin/pan as a
+// substring" test — it exists specifically so a future edit cannot add either back silently.
+/**
+ * Drops everything that is not a letter or digit, so separator conventions do not decide whether
+ * a guard fires. Over-matching is the safe direction here and is the point: this guard fails
+ * closed, and the cost of a false positive is a field an agent must leave to the user.
+ *
+ * Normalizes before squashing rather than after, because the naive squash used to *delete* any
+ * character outside ASCII `[a-z0-9]` instead of folding it. Deleting, not folding, is the bug:
+ * replacing one letter of a trigger word with a look-alike codepoint (fullwidth, accented, …)
+ * used to remove that letter from the squashed string entirely, so `ｐassword` (fullwidth
+ * U+FF50 `ｐ`) squashed to `assword` and matched nothing. NFKC folds that class of look-alike —
+ * fullwidth/halfwidth forms, and the Latin compatibility block — to its ordinary ASCII form
+ * before the letter can be deleted. The NFD pass afterward strips combining marks so an accented
+ * letter (`á` → `a` + combining acute) folds the same way once the mark itself is dropped.
+ *
+ * This does NOT close the general homoglyph class. NFKC has no cross-script confusables table:
+ * Cyrillic `а` (U+0430) and Greek `ο` (U+03BF) stay distinct codepoints from Latin `a`/`o` after
+ * NFKC, so `pаssword` (Cyrillic а) still squashes to something other than `password` and still
+ * bypasses `SUSPICIOUS_NAME`. Closing that would need an explicit confusables-folding table
+ * (e.g. Unicode TR39's) mapping each look-alike script's letters onto Latin before squashing —
+ * deliberately not built here; see the "known limit" test in guards.test.ts for the concrete gap.
+ */
+function squashSeparators(value) {
+    const foldedWidth = value.normalize('NFKC');
+    const withoutMarks = foldedWidth.normalize('NFD').replace(/\p{M}/gu, '');
+    return withoutMarks.replace(/[^a-z0-9]/gi, '');
+}
+/**
+ * Input types that hold no text.
+ *
+ * Writing to one succeeds mechanically and accomplishes nothing: setting `value` on a checkbox
+ * changes the string submitted *if* it is ticked, and leaves `checked` alone. The caller is told
+ * the fill worked and the box is still clear — a false success, which is worse than a refusal
+ * because it is never retried.
+ */
+const NON_TEXT_TYPES = new Set(['checkbox', 'radio', 'submit', 'reset', 'button']);
+/**
+ * Why this field's current value must not be reported back to a caller, or `null` when reading
+ * it is safe.
+ *
+ * Reading is the strictly more dangerous direction: writing into a password box gives an agent
+ * nothing, whereas reading one out hands over the secret itself. So every secrecy signal the fill
+ * guard uses applies here identically — type, autocomplete token, and a name or id that indicates
+ * a credential or anti-forgery token — and none of them may be relaxed for reads.
+ *
+ * @param field - The field's attributes.
+ * @returns The first secrecy refusal, or `null` when the value may be reported.
+ */
+export function findFieldReadRefusal(field) {
+    const type = field.type?.toLowerCase();
+    if (type !== undefined && DENIED_TYPES.has(type))
+        return 'denied-type';
+    const autocomplete = field.autocomplete?.toLowerCase();
+    if (autocomplete !== undefined) {
+        // The real grammar is space-separated tokens, but a comma-joined value
+        // (`"new-password,current-password"`) is markup an attacker-controlled page can trivially
+        // emit even though real browsers won't autofill it correctly either — splitting on
+        // whitespace alone turned the whole string into one unrecognized token, so the field still
+        // worked as a plain text input while looking unguarded.
+        for (const token of autocomplete.split(/[\s,]+/)) {
+            if (DENIED_AUTOCOMPLETE.has(token))
+                return 'denied-autocomplete';
+        }
+    }
+    if (SUSPICIOUS_NAME.test(squashSeparators(field.name ?? ''))
+        || SUSPICIOUS_NAME.test(squashSeparators(field.id ?? ''))
+        // `name`/`id` are the *machine* names; a form builder or CMS that emits `name="field_47"`
+        // next to a visible "Card number" label left the guard nothing to judge until this existed.
+        || SUSPICIOUS_NAME.test(squashSeparators(field.accessibleLabel ?? ''))) {
+        return 'suspicious-name';
+    }
+    return null;
+}
+/**
+ * Why an automated fill must be refused for this field, or `null` when it is safe to write.
+ *
+ * Fails closed on anything that looks like a credential, payment instrument, one-time code, or
+ * anti-forgery token, independent of whether the field carries an agent handle. Tagging a
+ * password box does not make it fillable. Every secrecy refusal is also a fill refusal — a field
+ * whose contents an agent may not read is certainly not one it may overwrite — and two further
+ * refusals cover fields that are simply not writable.
+ *
+ * @param field - The field's attributes.
+ * @returns The first refusal reason, or `null` when the field may be filled.
+ */
+export function findFieldFillRefusal(field) {
+    const secrecy = findFieldReadRefusal(field);
+    if (secrecy !== null)
+        return secrecy;
+    const type = field.type?.toLowerCase();
+    if (type !== undefined && NON_TEXT_TYPES.has(type))
+        return 'not-text';
+    if (field.readOnly === true)
+        return 'read-only';
+    if (field.disabled === true)
+        return 'disabled';
+    return null;
+}
+const FIELD_REFUSAL_MESSAGES = {
+    'denied-type': 'this field type can never be filled by an agent',
+    'denied-autocomplete': 'this field holds a credential or payment instrument',
+    'suspicious-name': 'this field name indicates a secret or anti-forgery token',
+    'not-text': 'this control holds no text — activate it with the click verb instead of filling it',
+    'read-only': 'this field is read-only',
+    disabled: 'this field is disabled',
+};
+const FIELD_READ_REFUSAL_MESSAGES = {
+    'denied-type': 'this field type is never readable by an agent',
+    'denied-autocomplete': 'this field holds a credential or payment instrument',
+    'suspicious-name': 'this field name indicates a secret or anti-forgery token',
+};
+/** Model-readable reason for a refusal, so a blocked fill explains itself instead of failing opaquely. */
+export function describeFieldRefusal(refusal) {
+    return FIELD_REFUSAL_MESSAGES[refusal];
+}
+/** Model-readable reason a value was withheld, so a caller knows the field has contents it may not see rather than assuming it is empty. */
+export function describeFieldReadRefusal(refusal) {
+    return FIELD_READ_REFUSAL_MESSAGES[refusal];
+}
+/** Default cap on page-authored text handed to a model. */
+export const MAX_AGENT_LABEL_LENGTH = 200;
+/**
+ * C0/C1 control characters plus the Unicode bidirectional and invisible formatting ranges.
+ *
+ * The bidi overrides matter as much as the control codes: `U+202E` and friends let page text
+ * render one way and read another, which is a direct way to smuggle a different instruction
+ * into whatever reads the label back.
+ */
+const CONTROL_AND_BIDI = 
+// eslint-disable-next-line no-control-regex
+/[\u0000-\u001F\u007F-\u009F\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g;
+/**
+ * Normalizes page-authored text before it reaches a model.
+ *
+ * Strips control characters (including the bidirectional overrides used to make text render
+ * differently from how it reads), collapses whitespace, and caps the length. The result is still
+ * untrusted *content* — this only bounds it; it does not make it safe to follow as instruction.
+ *
+ * @param raw - Text read off the page, e.g. a `data-agent-label`.
+ * @param maxLength - Cap, defaulting to {@link MAX_AGENT_LABEL_LENGTH}.
+ * @returns The bounded text and whether anything was cut.
+ */
+export function normalizeAgentLabel(raw, maxLength = MAX_AGENT_LABEL_LENGTH) {
+    const stripped = raw.replace(CONTROL_AND_BIDI, ' ');
+    const collapsed = stripped.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= maxLength)
+        return { text: collapsed, truncated: false };
+    return { text: collapsed.slice(0, maxLength), truncated: true };
+}
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAwBH,yDAAyD;AACzD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtE,wFAAwF;AACxF,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IAClC,kBAAkB,EAAE,cAAc,EAAE,eAAe;IACnD,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS;CACrF,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,eAAe,GACnB,+OAA+O,CAAC;AAElP,yFAAyF;AACzF,uFAAuF;AACvF,2FAA2F;AAC3F,kFAAkF;AAClF,wFAAwF;AACxF,6FAA6F;AAE7F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,YAAY,GAAG,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACzE,OAAO,YAAY,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAeD;;;;;;;GAOG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAInF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAsB;IACzD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC;IACvC,IAAI,IAAI,KAAK,SAAS,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,aAAa,CAAC;IAEvE,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,EAAE,WAAW,EAAE,CAAC;IACvD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,uEAAuE;QACvE,0FAA0F;QAC1F,mFAAmF;QACnF,2FAA2F;QAC3F,wDAAwD;QACxD,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjD,IAAI,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO,qBAAqB,CAAC;QACnE,CAAC;IACH,CAAC;IAED,IACE,eAAe,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;WACrD,eAAe,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,0FAA0F;QAC1F,4FAA4F;WACzF,eAAe,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,EACtE,CAAC;QACD,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAsB;IACzD,MAAM,OAAO,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IACrC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC;IACvC,IAAI,IAAI,KAAK,SAAS,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IACtE,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IAChD,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAC/C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,sBAAsB,GAAiC;IAC3D,aAAa,EAAE,iDAAiD;IAChE,qBAAqB,EAAE,qDAAqD;IAC5E,iBAAiB,EAAE,0DAA0D;IAC7E,UAAU,EAAE,oFAAoF;IAChG,WAAW,EAAE,yBAAyB;IACtC,QAAQ,EAAE,wBAAwB;CACnC,CAAC;AAEF,MAAM,2BAA2B,GAAqC;IACpE,aAAa,EAAE,+CAA+C;IAC9D,qBAAqB,EAAE,qDAAqD;IAC5E,iBAAiB,EAAE,0DAA0D;CAC9E,CAAC;AAEF,0GAA0G;AAC1G,MAAM,UAAU,oBAAoB,CAAC,OAAqB;IACxD,OAAO,sBAAsB,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC;AAED,4IAA4I;AAC5I,MAAM,UAAU,wBAAwB,CAAC,OAAyB;IAChE,OAAO,2BAA2B,CAAC,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,gBAAgB;AACpB,4CAA4C;AAC5C,yFAAyF,CAAC;AAO5F;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,SAAS,GAAG,sBAAsB;IACjF,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,IAAI,SAAS,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAChF,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAClE,CAAC"}

package/dist/handle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module handle
+ *
+ * `agentHandle('save')` — the attribute props a component spreads onto its root element to
+ * publish itself under this package's `data-agent-*` markup convention (see
+ * `element-handles.ts`), without the caller having to know the attribute names or re-derive the
+ * handle-validity rule itself.
+ *
+ * Deliberately pure data, no DOM: this returns a plain object of string attributes, spreadable by
+ * React (`<button {...agentHandle('save')}>`), Vue, Svelte, or any renderer that accepts arbitrary
+ * attribute props on an element. That is what lets it live in this package's universal root
+ * rather than `./dom` — nothing here touches `document` or any browser global.
+ */
+import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, type AgentElementRole } from './element-handles.js';
+/** Optional markup to attach alongside the handle itself. */
+export interface AgentHandleOptions {
+    /** What verb applies to this element — see {@link AgentElementRole}. */
+    readonly role?: AgentElementRole;
+    /** Stable, page-authored ontology for this element (e.g. `"Full name"`). Never live text. */
+    readonly label?: string;
+    /** Which published page this element belongs to, for a multi-page host. */
+    readonly page?: string;
+}
+/** The attribute props {@link agentHandle} returns, ready to spread onto an element. */
+export type AgentHandleProps = {
+    readonly [AGENT_ELEMENT_ATTRIBUTE]: string;
+} & Partial<Record<typeof AGENT_ROLE_ATTRIBUTE | typeof AGENT_LABEL_ATTRIBUTE | typeof AGENT_PAGE_ATTRIBUTE, string>>;
+/**
+ * Builds the attribute props that publish `handle` as an agent-addressable element.
+ *
+ * @param handle - The handle to publish. Must satisfy {@link isValidElementHandle} — this
+ *   function reuses that exact rule rather than a second, possibly-diverging check, since an
+ *   adversarial probe already confirmed it rejects quotes, brackets, backslashes, unicode and
+ *   overlong handles (see `element-handles.ts`).
+ * @param options - Optional role/label/page markup.
+ * @returns Attribute props to spread onto the element that should carry this handle.
+ * @throws If `handle` is not a valid element handle — never publishes a handle a caller (`page.*`
+ *   capabilities, `resolveHandleSelector`) could not later resolve.
+ */
+export declare function agentHandle(handle: string, options?: AgentHandleOptions): AgentHandleProps;
+//# sourceMappingURL=handle.d.ts.map

package/dist/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EAEpB,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAC5C,GAAG,OAAO,CACT,MAAM,CACJ,OAAO,oBAAoB,GAAG,OAAO,qBAAqB,GAAG,OAAO,oBAAoB,EACxF,MAAM,CACP,CACF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,gBAAgB,CAY9F"}

package/dist/handle.js

@@ -0,0 +1,41 @@
+/**
+ * @module handle
+ *
+ * `agentHandle('save')` — the attribute props a component spreads onto its root element to
+ * publish itself under this package's `data-agent-*` markup convention (see
+ * `element-handles.ts`), without the caller having to know the attribute names or re-derive the
+ * handle-validity rule itself.
+ *
+ * Deliberately pure data, no DOM: this returns a plain object of string attributes, spreadable by
+ * React (`<button {...agentHandle('save')}>`), Vue, Svelte, or any renderer that accepts arbitrary
+ * attribute props on an element. That is what lets it live in this package's universal root
+ * rather than `./dom` — nothing here touches `document` or any browser global.
+ */
+import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, isValidElementHandle, } from './element-handles.js';
+/**
+ * Builds the attribute props that publish `handle` as an agent-addressable element.
+ *
+ * @param handle - The handle to publish. Must satisfy {@link isValidElementHandle} — this
+ *   function reuses that exact rule rather than a second, possibly-diverging check, since an
+ *   adversarial probe already confirmed it rejects quotes, brackets, backslashes, unicode and
+ *   overlong handles (see `element-handles.ts`).
+ * @param options - Optional role/label/page markup.
+ * @returns Attribute props to spread onto the element that should carry this handle.
+ * @throws If `handle` is not a valid element handle — never publishes a handle a caller (`page.*`
+ *   capabilities, `resolveHandleSelector`) could not later resolve.
+ */
+export function agentHandle(handle, options = {}) {
+    if (!isValidElementHandle(handle)) {
+        throw new Error(`invalid element handle "${handle.slice(0, 128)}": `
+            + 'handles are lowercase words joined by single hyphens, and are never CSS selectors');
+    }
+    const props = { [AGENT_ELEMENT_ATTRIBUTE]: handle };
+    if (options.role !== undefined)
+        props[AGENT_ROLE_ATTRIBUTE] = options.role;
+    if (options.label !== undefined)
+        props[AGENT_LABEL_ATTRIBUTE] = options.label;
+    if (options.page !== undefined)
+        props[AGENT_PAGE_ATTRIBUTE] = options.page;
+    return props;
+}
+//# sourceMappingURL=handle.js.map

package/dist/handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.js","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GAErB,MAAM,sBAAsB,CAAC;AAsB9B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,UAA8B,EAAE;IAC1E,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,2BAA2B,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK;cAClD,mFAAmF,CACtF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAA2B,EAAE,CAAC,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5E,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3E,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;IAC9E,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3E,OAAO,KAAyB,CAAC;AACnC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @jini-ai/agentic — the framework-free half of agent control.
+ *
+ * Everything an outside caller needs to drive a Jini frontend, with no React, no DOM, and no
+ * transport: the capability vocabulary, the two shipped manifests, the `data-agent-*` markup
+ * convention, and the refusals that must hold everywhere.
+ *
+ * Framework bindings (`@jini-ai/chat-react`, via `@jini-ai/agentic/dom`'s `createDomPageDriver`, and
+ * any Vue/Svelte sibling) import from here and add only the wiring their framework needs.
+ * Server-side hosts (an HTTP route table, an MCP stdio server) import the same manifests, so the
+ * two can never drift apart.
+ *
+ * What is deliberately NOT here: how an action reaches a page. That is a transport concern —
+ * same-document in a real site like a CMS, `postMessage` when a host embeds an untrusted
+ * preview in a sandboxed frame. The verbs are identical either way. Also not here: any product's
+ * OWN capabilities (`@jini-ai/chat-core`'s `chat.*` verbs stay in chat-core, which depends on this
+ * package for the vocabulary rather than the other way around) — see this package's
+ * source-map.md for why the split is real rather than a wholesale relocation.
+ */
+export { findCapability, findCapabilityInputError, availableCapabilities, type CapabilityDef, type CapabilityInputSchema, type CapabilityRisk, type CapabilitySurface, } from './capability.js';
+export type { PageDriver, FindElementsFilter } from './page-driver.js';
+export { executePageCapability, projectElementState, DEFAULT_HIGHLIGHT_MS, MAX_HIGHLIGHT_MS, MAX_STATEFUL_ELEMENTS, type FindElementsResult, type PageElementResult, type PageSummary, type PageWriteObservation, } from './page-executor.js';
+export { PAGE_CAPABILITIES } from './page-capabilities.js';
+export { AGENT_ELEMENT_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ELEMENT_ROLES, isValidElementHandle, resolveHandleSelector, type AgentElementRole, type AgentElementDescriptor, type AgentElementRawState, type AgentElementState, } from './element-handles.js';
+export { agentHandle, type AgentHandleOptions, type AgentHandleProps } from './handle.js';
+export { findFieldFillRefusal, findFieldReadRefusal, describeFieldRefusal, describeFieldReadRefusal, normalizeAgentLabel, MAX_AGENT_LABEL_LENGTH, type FieldDescriptor, type FieldRefusal, type FieldReadRefusal, type NormalizedLabel, } from './guards.js';
+/**
+ * Protocol adapters, named for what they derive from.
+ *
+ * Each is a ONE-WAY projection out of the neutral core: they import `capability.js`, and nothing
+ * imports back. That direction is the whole point — if the core ever imported an adapter, the
+ * protocol we happened to build against would leak into the vocabulary and the layer would stop
+ * being neutral. None of them opens a connection or touches a browser global; a framework
+ * binding owns transport and host access.
+ */
+export { toWebMcpTool, toWebMcpTools, WebMcpConfirmationRequiredError, type WebMcpToolRegistration, type WebMcpUserInteraction, type RequestUserInteraction, type ToWebMcpToolOptions, } from './webmcp.js';
+/**
+ * Genuine AG-UI: the {@link CapabilityDef} → AG-UI *frontend tool* projection. Real conformance —
+ * it emits the protocol's own `parameters` field name (not `inputSchema`) and its canonical
+ * `TOOL_CALL_START`/`TOOL_CALL_ARGS`/`TOOL_CALL_END` event names, all three of which appear in
+ * AG-UI's published `EventType` enum.
+ */
+export { toAgUiTool, toAgUiTools, createAgUiToolResult, AG_UI_TOOL_CALL_EVENTS, type AgUiTool, type AgUiToolResultMessage, } from './ag-ui.js';
+/**
+ * Jini's **own** run-stream surface protocol, from `./gen-ui/` — six event kinds and the encoder
+ * that produces them (folded in 2026-07-26 from the standalone `@jini-ai/agui` package, plan §3a).
+ *
+ * Renamed from `./agui/` on 2026-07-27, because this is NOT AG-UI. The real Agent-User Interaction
+ * Protocol (https://github.com/ag-ui-protocol/ag-ui) carries a 33-member `SCREAMING_SNAKE` event
+ * enum — `RUN_STARTED`, `TEXT_MESSAGE_CONTENT`, `STATE_DELTA`, `STEP_STARTED`, `REASONING_*` — and
+ * shares **zero** event names with the six dotted-lowercase kinds in `./gen-ui/events.ts`, which
+ * are a de-branded port of one product's internal run-event adapter. Carrying the AG-UI name on
+ * them asserted a conformance that does not exist.
+ *
+ * `./ag-ui.ts` above was wrongly folded in with them on 2026-07-26 and moved back out on the 27th:
+ * it is the one file here that really does speak AG-UI, so merging it with these six was the exact
+ * inversion of the truth.
+ *
+ * The exported symbols below still carry `Agui`/`AGUI` prefixes: renaming those crosses into
+ * `@jini-ai/http` (whose `RUN_STREAM_ROUTE_PATH` is `/api/runs/:runId/agui-stream`) and
+ * `@jini-ai/protocol`, so it is deliberately not bundled with this directory move.
+ */
+export { createAguiEncoder, type AguiEncodeContext, type AguiEncoder, type AGUIAgentMessageEvent, type AGUIEvent, type AGUIEventBase, type AGUIEventKind, type AGUIRunLifecycleEvent, type AGUIStateUpdateEvent, type AGUISurfaceRequestedEvent, type AGUISurfaceRespondedEvent, type AGUIToolCallEvent, } from './gen-ui/index.js';
+export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcNotification, type JsonRpcResponse, type JsonRpcError, } from './mcp-ui-apps.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE1F,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AAErB;;;;;;;;GAQG;AACH,OAAO,EACL,YAAY,EACZ,aAAa,EACb,+BAA+B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,OAAO,EACL,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,QAAQ,EACb,KAAK,qBAAqB,GAC3B,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,64 @@
+/**
+ * @jini-ai/agentic — the framework-free half of agent control.
+ *
+ * Everything an outside caller needs to drive a Jini frontend, with no React, no DOM, and no
+ * transport: the capability vocabulary, the two shipped manifests, the `data-agent-*` markup
+ * convention, and the refusals that must hold everywhere.
+ *
+ * Framework bindings (`@jini-ai/chat-react`, via `@jini-ai/agentic/dom`'s `createDomPageDriver`, and
+ * any Vue/Svelte sibling) import from here and add only the wiring their framework needs.
+ * Server-side hosts (an HTTP route table, an MCP stdio server) import the same manifests, so the
+ * two can never drift apart.
+ *
+ * What is deliberately NOT here: how an action reaches a page. That is a transport concern —
+ * same-document in a real site like a CMS, `postMessage` when a host embeds an untrusted
+ * preview in a sandboxed frame. The verbs are identical either way. Also not here: any product's
+ * OWN capabilities (`@jini-ai/chat-core`'s `chat.*` verbs stay in chat-core, which depends on this
+ * package for the vocabulary rather than the other way around) — see this package's
+ * source-map.md for why the split is real rather than a wholesale relocation.
+ */
+export { findCapability, findCapabilityInputError, availableCapabilities, } from './capability.js';
+export { executePageCapability, projectElementState, DEFAULT_HIGHLIGHT_MS, MAX_HIGHLIGHT_MS, MAX_STATEFUL_ELEMENTS, } from './page-executor.js';
+export { PAGE_CAPABILITIES } from './page-capabilities.js';
+export { AGENT_ELEMENT_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ELEMENT_ROLES, isValidElementHandle, resolveHandleSelector, } from './element-handles.js';
+export { agentHandle } from './handle.js';
+export { findFieldFillRefusal, findFieldReadRefusal, describeFieldRefusal, describeFieldReadRefusal, normalizeAgentLabel, MAX_AGENT_LABEL_LENGTH, } from './guards.js';
+/**
+ * Protocol adapters, named for what they derive from.
+ *
+ * Each is a ONE-WAY projection out of the neutral core: they import `capability.js`, and nothing
+ * imports back. That direction is the whole point — if the core ever imported an adapter, the
+ * protocol we happened to build against would leak into the vocabulary and the layer would stop
+ * being neutral. None of them opens a connection or touches a browser global; a framework
+ * binding owns transport and host access.
+ */
+export { toWebMcpTool, toWebMcpTools, WebMcpConfirmationRequiredError, } from './webmcp.js';
+/**
+ * Genuine AG-UI: the {@link CapabilityDef} → AG-UI *frontend tool* projection. Real conformance —
+ * it emits the protocol's own `parameters` field name (not `inputSchema`) and its canonical
+ * `TOOL_CALL_START`/`TOOL_CALL_ARGS`/`TOOL_CALL_END` event names, all three of which appear in
+ * AG-UI's published `EventType` enum.
+ */
+export { toAgUiTool, toAgUiTools, createAgUiToolResult, AG_UI_TOOL_CALL_EVENTS, } from './ag-ui.js';
+/**
+ * Jini's **own** run-stream surface protocol, from `./gen-ui/` — six event kinds and the encoder
+ * that produces them (folded in 2026-07-26 from the standalone `@jini-ai/agui` package, plan §3a).
+ *
+ * Renamed from `./agui/` on 2026-07-27, because this is NOT AG-UI. The real Agent-User Interaction
+ * Protocol (https://github.com/ag-ui-protocol/ag-ui) carries a 33-member `SCREAMING_SNAKE` event
+ * enum — `RUN_STARTED`, `TEXT_MESSAGE_CONTENT`, `STATE_DELTA`, `STEP_STARTED`, `REASONING_*` — and
+ * shares **zero** event names with the six dotted-lowercase kinds in `./gen-ui/events.ts`, which
+ * are a de-branded port of one product's internal run-event adapter. Carrying the AG-UI name on
+ * them asserted a conformance that does not exist.
+ *
+ * `./ag-ui.ts` above was wrongly folded in with them on 2026-07-26 and moved back out on the 27th:
+ * it is the one file here that really does speak AG-UI, so merging it with these six was the exact
+ * inversion of the truth.
+ *
+ * The exported symbols below still carry `Agui`/`AGUI` prefixes: renaming those crosses into
+ * `@jini-ai/http` (whose `RUN_STREAM_ROUTE_PATH` is `/api/runs/:runId/agui-stream`) and
+ * `@jini-ai/protocol`, so it is deliberately not bundled with this directory move.
+ */
+export { createAguiEncoder, } from './gen-ui/index.js';
+export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, } from './mcp-ui-apps.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,qBAAqB,GAKtB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,GAKtB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,GAKtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,WAAW,EAAkD,MAAM,aAAa,CAAC;AAE1F,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,GAKvB,MAAM,aAAa,CAAC;AAErB;;;;;;;;GAQG;AACH,OAAO,EACL,YAAY,EACZ,aAAa,EACb,+BAA+B,GAKhC,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,OAAO,EACL,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,sBAAsB,GAGvB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,iBAAiB,GAYlB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,GAMxB,MAAM,kBAAkB,CAAC"}

package/dist/mcp-ui-apps.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @module mcp-ui
+ *
+ * The MCP Apps (`mcp-ui`) envelope: JSON-RPC 2.0 over `postMessage` between a host and a
+ * sandboxed iframe View.
+ *
+ * MCP Apps became the first official MCP extension (SEP-1865) on 2026-01-26. Jini borrows its
+ * **envelope and lifecycle** rather than inventing a message format, because the hard parts are
+ * already settled there: request/response correlation by `id`, and the ordering rule that a host
+ * MUST NOT send any request or notification to a View before receiving `initialized` — which is
+ * the fix for the "posted before the iframe was listening" race.
+ *
+ * Two deliberate divergences, both load-bearing:
+ *
+ * 1. **Direction.** MCP Apps is View→Host: the embedded UI calls tools. Host→View is a *fixed*
+ *    lifecycle set ({@link MCP_UI_HOST_NOTIFICATIONS}) with no generic "host asks the View to do
+ *    something". Jini's page verbs therefore ride as an explicitly-namespaced extension
+ *    ({@link JINI_PAGE_ACTION_METHOD}) — ours, not the spec's, and named so no one mistakes it.
+ * 2. **Sandbox.** The spec mandates `sandbox="allow-scripts allow-same-origin"`, which is safe
+ *    *there* because the View is served from a separate origin behind a sandbox proxy. A host
+ *    serving preview content from its own origin must NOT copy that line: `allow-same-origin`
+ *    would hand the embedded document access to the host's origin. See
+ *    {@link MCP_UI_SANDBOX_NOTE}.
+ *
+ * No transport here — this package touches no browser globals. These are pure builders and
+ * parsers; the binding that owns the iframe does the posting.
+ */
+/** Method names the View may call on the Host. From the 2026-01-26 specification. */
+export declare const MCP_UI_VIEW_METHODS: {
+    readonly initialize: "ui/initialize";
+    readonly callTool: "tools/call";
+    readonly readResource: "resources/read";
+    readonly log: "notifications/message";
+    readonly openLink: "ui/open-link";
+    readonly sendMessage: "ui/message";
+    readonly requestDisplayMode: "ui/request-display-mode";
+    readonly updateModelContext: "ui/update-model-context";
+    readonly ping: "ping";
+};
+/**
+ * Notifications the Host may send the View. This is the complete host→view surface in the
+ * specification — note that none of them is a generic page action.
+ */
+export declare const MCP_UI_HOST_NOTIFICATIONS: {
+    readonly initialized: "ui/notifications/initialized";
+    readonly toolInputPartial: "ui/notifications/tool-input-partial";
+    readonly toolInput: "ui/notifications/tool-input";
+    readonly toolResult: "ui/notifications/tool-result";
+    readonly toolCancelled: "ui/notifications/tool-cancelled";
+    readonly sizeChanged: "ui/notifications/size-changed";
+    readonly hostContextChanged: "ui/notifications/host-context-changed";
+    readonly teardown: "ui/resource-teardown";
+};
+/**
+ * Jini's page-action extension. **Not part of MCP Apps** — the namespace is explicit so it can
+ * never be mistaken for a spec method, and so a compliant host that does not understand it
+ * rejects it as unknown rather than silently mis-handling it.
+ */
+export declare const JINI_PAGE_ACTION_METHOD = "x-jini/page-action";
+/**
+ * Why a host serving preview content from its own origin must not copy the spec's sandbox line.
+ * Kept as an exported string so the reason travels with the code that would otherwise be
+ * cargo-culted.
+ */
+export declare const MCP_UI_SANDBOX_NOTE: string;
+export interface JsonRpcRequest {
+    readonly jsonrpc: '2.0';
+    readonly id: number | string;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+export interface JsonRpcNotification {
+    readonly jsonrpc: '2.0';
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+export interface JsonRpcError {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export interface JsonRpcResponse {
+    readonly jsonrpc: '2.0';
+    readonly id: number | string;
+    readonly result?: unknown;
+    readonly error?: JsonRpcError;
+}
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+/** JSON-RPC 2.0 reserved codes, used so a View's failures read the same as any other client's. */
+export declare const JSON_RPC_ERROR_CODES: {
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+};
+/**
+ * Whether an arbitrary value is a JSON-RPC 2.0 message.
+ *
+ * Messages arriving over `postMessage` are attacker-influenced input — any page able to reach the
+ * frame can post anything. Validate before dispatch; never trust the shape.
+ *
+ * @param value - The raw `event.data`.
+ * @returns True when the value is a well-formed JSON-RPC message.
+ */
+export declare function isJsonRpcMessage(value: unknown): value is JsonRpcMessage;
+/** Whether a validated message expects a response (as opposed to being a notification). */
+export declare function isJsonRpcRequest(message: JsonRpcMessage): message is JsonRpcRequest;
+/**
+ * Builds a request.
+ *
+ * @param id - Correlation id, unique per in-flight request. Doubles as the idempotency key: a
+ * transport that redelivers (an SSE reconnect, a repeated post) must not execute twice.
+ * @param method - Method name.
+ * @param params - Optional parameters.
+ */
+export declare function createJsonRpcRequest(id: number | string, method: string, params?: Record<string, unknown>): JsonRpcRequest;
+/** Builds a notification — no `id`, so no response is expected or allowed. */
+export declare function createJsonRpcNotification(method: string, params?: Record<string, unknown>): JsonRpcNotification;
+/** Builds a success response for `id`. */
+export declare function createJsonRpcResult(id: number | string, result: unknown): JsonRpcResponse;
+/** Builds an error response for `id`. */
+export declare function createJsonRpcError(id: number | string, code: number, message: string, data?: unknown): JsonRpcResponse;
+/**
+ * Builds a Jini page-action request.
+ *
+ * @param id - Correlation/idempotency id.
+ * @param capabilityId - A `page.*` capability id.
+ * @param input - Capability arguments.
+ * @returns The namespaced extension request.
+ */
+export declare function createPageActionRequest(id: number | string, capabilityId: string, input: Record<string, unknown>): JsonRpcRequest;
+//# sourceMappingURL=mcp-ui-apps.d.ts.map

package/dist/mcp-ui-apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-ui-apps.d.ts","sourceRoot":"","sources":["../src/mcp-ui-apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qFAAqF;AACrF,eAAO,MAAM,mBAAmB;;;;;;;;;;CAUtB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;CAS5B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAGkE,CAAC;AAEnG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,mBAAmB,GAAG,eAAe,CAAC;AAEpF,kGAAkG;AAClG,eAAO,MAAM,oBAAoB;;;;;;CAMvB,CAAC;AAMX;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAKxE;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,IAAI,cAAc,CAEnF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,cAAc,CAEhB;AAED,8EAA8E;AAC9E,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,mBAAmB,CAErB;AAED,0CAA0C;AAC1C,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,eAAe,CAEzF;AAED,yCAAyC;AACzC,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,GACb,eAAe,CAEjB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,cAAc,CAEhB"}