@onlyworlds/sdk 4.71.0 → 4.72.0

package/AGENTS.md

@@ -56,6 +56,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   account's daily token rating (`tokens_remaining`, `token_rating`; `remaining` counts answers of
   this size still in it); used up → `err.isQuotaExceeded`. `isAskUnavailable`, `isAskFailed`
   count nothing. Custom fields (`x_*`) are in the lookup and the context; `atlas_*` is not.
+  Since 4.72.0 `buildAskContext` leaves proposed (`x_review_proposed` not absent or null), hidden
+  (`hidden` not absent, null or false) and room elements out unless asked
+  (`{ includeProposed, includeHidden, includeRoom }`), lists their ids in `leftOut.proposed`,
+  `.hidden`, `.room` (hidden and proposed: under `hidden` only), and labels a proposed element it
+  sends `[proposed, not yet reviewed]` on its first line; say how many were held back.
 - Sort (since 4.18.0, account token): `account.sort({ worldId, notes, slice })` turns unsorted
   notes (text, or a picture already uploaded into the world) into rows to review: `make`,
   `add_to`, `link`, `ask`, plus `not_proposed` with reasons. Ids come only from your `slice`

package/CHANGELOG.md

@@ -5,6 +5,19 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.72.0] - 2026-10-24
+
+### Changed
+
+- **`buildAskContext` now leaves proposed, hidden and room elements out of the context unless asked.** A caller that passes such elements gets fewer items in `context` and `kept` than before: an element whose `x_review_proposed` is anything but absent or null (the review profile, rules 1 and 4: a value that is not a proper mark is a doubt and counts as proposed), one whose `hidden` is anything but absent, null or false (folder format §4.8, the same test as `writeWorldFile`'s `includeHidden`), and a room element (`isRoomElement`, the room profile, rules 1 and 4) are not sent. Their ids come back in the new `leftOut: { proposed, hidden, room }`, in the order given, so a tool can say how many it held back. An element carrying more than one mark is listed once, in the first of hidden, proposed, room whose option is off: a hidden proposed element is under `hidden`, so `includeProposed` alone never sends it. A sent element's link to an element a mark leaves out, anywhere in the index, reads as "not present in the world data", never by its name. `dropped` keeps its meaning (the 8 items and the 12,000 characters), counted over what remains. Until now the SDK relied on the caller (Lantern) to filter first; the rules bind the exported function itself.
+
+### Added
+
+- **`buildAskContext(items, index, { includeProposed, includeHidden, includeRoom })`**, each default false: true sends that kind again. A proposed element sent carries the review profile's label on its first line, `[proposed, not yet reviewed] Name (type)`, where the AI reading the text sees it. An option that is not a boolean is a TypeError, and an unknown key is refused by name (the options fence, `test/options.test.mjs`). Types `OwAskContextOptions` and `OwAskLeftOut`.
+- **`REVIEW_PROPOSED_LABEL`** (`'proposed, not yet reviewed'`), generated into `types.generated.ts` from rule 1's own sentence in the vendored `profiles/review.md` ("labels each one it keeps **"…"**"); codegen exits 1 if the sentence is missing or occurs twice.
+- **`minted_by: string | null` on `OwWorldLink` and `OwCreatedWorldLink`** (keel PR 215): the membership (its id in GET /api/v2/members) of the co-builder who minted the link over POST /api/v2/links; null for a link the owner made. Served by `createWorldLink` and `listWorldLinks`. No client for `/api/v2/links` itself yet.
+- Tests: each mark left out by default and listed; `hidden` as §4.8 reads it (`"true"` and 1 out, false and null in); a doubt (`"yes"`, `{}`) treated as proposed and labelled when asked, a cleared `null` settled; each `include*` bringing back its own kind only; the label on the first line; a hidden proposed element counted once, under hidden; a kept element's links to a hidden element and from a room element read without their names; the limits over what remains; the fence and the boolean check. Ten mutants, each red on its own test: no proposed filter, no hidden filter, no room filter, no label, a doubt not proposed, proposed checked before hidden, left-out elements counted toward the total, no link view, no option fence, no boolean check.
+
 ## [4.71.0] - 2026-10-24
 
 ### Added

package/README.md

@@ -247,11 +247,13 @@ To have an answer written from what you found, OnlyWorlds runs a small AI proxy
 
 ```typescript
 const shown = hits.slice(0, 8);                          // what your screen lists
-const { context, kept } = buildAskContext(shown, index); // within the proxy's limits; kept = what was sent
+const { context, kept, leftOut } = buildAskContext(shown, index); // within the proxy's limits; kept = what was sent
 const reply = await account.ask({ worldId, question, context }); // account: a client with an ow_a_ token
 reply.answer;                                            // from those elements only, or "The world doesn't say."
 ```
 
+`buildAskContext` hands world elements to an AI, so it leaves three kinds out unless you ask (since 4.72.0): elements marked proposed (`x_review_proposed` anything but absent or null), elements marked hidden (`hidden` anything but absent, null or false) and room elements (`isRoomElement`). Their ids come back in `leftOut.proposed`, `leftOut.hidden` and `leftOut.room`, so you can say how many were held back; an element both hidden and proposed is listed under `hidden` only. Pass `{ includeProposed: true }`, `{ includeHidden: true }` or `{ includeRoom: true }` to send them; a proposed element sent carries `[proposed, not yet reviewed]` (`REVIEW_PROPOSED_LABEL`) on its first line. A sent element's link to one left out reads as not present, never by its name. `dropped` stays the proxy's limits: past the 8th, or past the 12,000 characters, counted over what remains.
+
 The same proxy sorts loose notes into changes for the user to review. Send the elements your own lookup found for them as the `slice`; every id in a row comes from it, and nothing is written until your app applies what the user accepts.
 
 ```typescript

package/dist/index.d.ts

@@ -102,6 +102,12 @@ declare const ROOM_PAIRS: ReadonlyArray<{
     readonly type: ElementType;
     readonly supertype: string;
 }>;
+/** The review profile's label (schema-dist `profiles/review.md`, rule 1): the words a reader that
+ *  hands a world on (a context for an AI, a pack, a share) puts on each proposed element it keeps,
+ *  one whose `x_review_proposed` is anything but absent or null (a doubt, rule 4, included).
+ *  buildAskContext writes it on the element's first line. Source: rule 1's own sentence, read at
+ *  codegen. */
+declare const REVIEW_PROPOSED_LABEL: "proposed, not yet reviewed";
 /** Field type definitions for OnlyWorlds elements. */
 type FieldType = 'text' | 'integer'
 /**
@@ -2635,6 +2641,8 @@ interface OwWorldLink {
     uses: number;
     /** A table is `pending` while `uses < max_uses` (and neither revoked nor expired), `used` once full. */
     status: 'pending' | 'used' | 'revoked' | 'expired';
+    /** The membership (its id in GET /api/v2/members) of the co-builder who minted the link over POST /api/v2/links; null for a link the owner made (keel PR 215). */
+    minted_by: string | null;
     /** Whether the link shows the world's name and picture when it is pasted into a chat (keel #422): then the link is `/join/<world_id>#<code>`, else `/join#<code>`. Never on an agent link. */
     preview?: boolean;
     /** A player link only: the Character the player reads as; null while a link for a fresh Character is unused, and always null on a table. `name` is null if that Character was deleted (the redeem then makes a fresh one). */
@@ -4285,7 +4293,7 @@ declare class OwV2Client {
     /**
      * POST /account/ask -- a question about a world the account owns or is in, answered by
      * keel's AI proxy from `context` only (build it with buildAskContext from the elements
-     * the user sees). The answer is "The world doesn't say." when the context does not hold
+     * the user sees; it leaves proposed, hidden and room elements out unless asked). The answer is "The world doesn't say." when the context does not hold
      * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
      * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's token rating used up for the day;
      * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
@@ -4814,11 +4822,20 @@ declare function renderElement<T extends OwLookupElement>(element: T, index: OwW
  * the answer's sources are what the user saw, never a second lookup's.
  *
  *   const hits = lookupWorld(index, question).slice(0, 8);   // what the screen lists
- *   const { context, kept } = buildAskContext(hits, index);
+ *   const { context, kept, leftOut } = buildAskContext(hits, index);
  *   const reply = await account.ask({ worldId, question, context });
  *
+ * It is a reader that hands a world on, so three published rules hold here, not only in
+ * the caller: an element marked proposed (the review profile, rules 1 and 4: any
+ * `x_review_proposed` but absent or null, a doubt included), one marked hidden (folder
+ * format §4.8: a `hidden` but absent, null or false) and a room element (the room
+ * profile, rules 1 and 4: `isRoomElement`) are left out unless asked for, and listed in
+ * `leftOut`. A kept proposed element carries REVIEW_PROPOSED_LABEL on its first line. A
+ * kept element's link to one left out reads as not present, never by its name.
+ *
  * The limits are keel's (accounts/ask.py), counted the way keel counts (characters,
- * not UTF-16 units): at most 8 items, 2,000 characters each, 12,000 in all.
+ * not UTF-16 units): at most 8 items, 2,000 characters each, 12,000 in all. They apply
+ * to what remains after the three rules.
  */
 
 /** keel's limits on one ask. */
@@ -4828,23 +4845,56 @@ declare const ASK_LIMITS: {
     readonly itemMax: 2000;
     readonly totalMax: 12000;
 };
+interface OwAskContextOptions {
+    /**
+     * Send proposed elements: those whose `x_review_proposed` is anything but absent or null
+     * (the review profile; a value that is not a proper mark is a doubt, rule 4, and counts as
+     * proposed). Each one sent carries REVIEW_PROPOSED_LABEL on its first line. Default false:
+     * left out and listed in `leftOut.proposed`.
+     */
+    includeProposed?: boolean;
+    /**
+     * Send elements marked hidden: a `hidden` that is anything but absent, null or false (folder
+     * format §4.8, the same test as writeWorldFile's `includeHidden`). Default false: left out and
+     * listed in `leftOut.hidden`.
+     */
+    includeHidden?: boolean;
+    /** Send room elements (`isRoomElement`, the room profile). Default false: left out and listed in `leftOut.room`. */
+    includeRoom?: boolean;
+}
+/** Ids left out by a mark, in the order given. An element carrying several marks is listed once, in the first of hidden, proposed, room whose `include*` is off. */
+interface OwAskLeftOut {
+    proposed: string[];
+    hidden: string[];
+    room: string[];
+}
 interface OwAskContext {
     /** The texts to send as `context`, in the order given. */
     context: string[];
     /** Ids of the elements sent, in order (one per `context` item). */
     kept: string[];
-    /** Ids of the elements left out: past the 8th, or from the first one the 12,000 total could not hold. */
+    /** Ids of the elements the limits left out: past the 8th, or from the first one the 12,000 total could not hold. Never an element `leftOut` holds. */
     dropped: string[];
     /** Ids among `kept` whose text was cut to 2,000 characters. */
     truncated: string[];
+    /** Ids of the elements a mark left out (proposed, hidden, room), before the limits were counted. */
+    leftOut: OwAskLeftOut;
 }
 /**
  * Turn the elements on screen into the proxy's `context`. Takes lookup hits or plain
- * elements, keeps their order, renders each with `renderElement`, cuts a text over
- * 2,000 characters, and stops at the 8th or at the first one the 12,000 total cannot
- * hold, so what is sent is always the top of the list as shown.
+ * elements and keeps their order. First the three marks: an element marked hidden
+ * (§4.8), proposed (the review profile, a doubt included) or a room element (the room
+ * profile) is left out unless its `include*` option is true, and its id goes to
+ * `leftOut` (one bucket each, in the order hidden, proposed, room: a hidden proposed
+ * element is listed under `hidden` only, since the owner's hide is the stronger
+ * withholding and `includeProposed` alone never sends it). Then each remaining element
+ * is rendered with `renderElement` (a proposed one with REVIEW_PROPOSED_LABEL on its
+ * first line; a link to an element a mark leaves out, anywhere in the index, reads as
+ * not present), a text over 2,000 characters is cut, and the list stops at the 8th or
+ * at the first the 12,000 total cannot hold, so what is sent is always the top of the
+ * list as shown. An unknown option, or one that is not a boolean, is a TypeError.
  */
-declare function buildAskContext<T extends OwLookupElement>(items: Array<OwLookupHit<T> | T>, index: OwWorldIndex<T>): OwAskContext;
+declare function buildAskContext<T extends OwLookupElement>(items: Array<OwLookupHit<T> | T>, index: OwWorldIndex<T>, opts?: OwAskContextOptions): OwAskContext;
 
 /**
  * Photo preparation: make a picture from a phone's camera or files ready for
@@ -5483,4 +5533,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAccountWorld, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreateAccountWorldInput, type OwCreatedAccountWorld, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtCompact, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, type OwMintedKey, type OwNamesMap, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwProposedNewElement, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwReviewInput, type OwReviewed, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldOrigin, type OwWorldProducer, type OwWorldProposalList, type OwWorldProposalQuery, type OwWorldProposalRow, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, type OwWriteWorldFileReport, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, nfc, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };
+export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAccountWorld, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAskContextOptions, type OwAskLeftOut, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreateAccountWorldInput, type OwCreatedAccountWorld, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtCompact, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, type OwMintedKey, type OwNamesMap, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwProposedNewElement, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwReviewInput, type OwReviewed, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldOrigin, type OwWorldProducer, type OwWorldProposalList, type OwWorldProposalQuery, type OwWorldProposalRow, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, type OwWriteWorldFileReport, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, REVIEW_PROPOSED_LABEL, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, nfc, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -1746,7 +1746,7 @@ var OwV2Client = class {
   /**
    * POST /account/ask -- a question about a world the account owns or is in, answered by
    * keel's AI proxy from `context` only (build it with buildAskContext from the elements
-   * the user sees). The answer is "The world doesn't say." when the context does not hold
+   * the user sees; it leaves proposed, hidden and room elements out unless asked). The answer is "The world doesn't say." when the context does not hold
    * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
    * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's token rating used up for the day;
    * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
@@ -2244,6 +2244,7 @@ var ROOM_PAIRS = [
   { type: "character", supertype: "Member" }
 ];
 var ROOM_MARK = "x_room_of";
+var REVIEW_PROPOSED_LABEL = "proposed, not yet reviewed";
 var FIELD_SCHEMA = {
   ability: {
     // Base fields (shared by all elements)
@@ -4118,19 +4119,60 @@ function renderElement(element, index, opts = {}) {
 
 // src/ask.ts
 var ASK_LIMITS = { questionMax: 500, itemsMax: 8, itemMax: 2e3, totalMax: 12e3 };
+var ASK_OPTION_KEYS = ["includeProposed", "includeHidden", "includeRoom"];
 var chars = (s) => [...s].length;
 var cut = (s, n) => [...s].slice(0, n).join("");
-function buildAskContext(items, index) {
-  const out = { context: [], kept: [], dropped: [], truncated: [] };
+var isHidden = (el) => el.hidden !== void 0 && el.hidden !== null && el.hidden !== false;
+var isProposed = (el) => el.x_review_proposed !== void 0 && el.x_review_proposed !== null;
+function readOptions(opts) {
+  refuseUnknownOptions("buildAskContext", opts, ASK_OPTION_KEYS);
+  const o = opts ?? {};
+  for (const k of ASK_OPTION_KEYS) {
+    if (o[k] !== void 0 && typeof o[k] !== "boolean") {
+      throw new TypeError(`buildAskContext: ${k} must be a boolean; got ${JSON.stringify(o[k]) ?? String(o[k])}.`);
+    }
+  }
+  return { includeProposed: o.includeProposed === true, includeHidden: o.includeHidden === true, includeRoom: o.includeRoom === true };
+}
+function buildAskContext(items, index, opts = {}) {
+  const o = readOptions(opts);
+  const markOf = (el) => {
+    if (!o.includeHidden && isHidden(el)) return "hidden";
+    if (!o.includeProposed && isProposed(el)) return "proposed";
+    if (!o.includeRoom && isRoomElement(el)) return "room";
+    return null;
+  };
+  const withheld = (id) => {
+    const el = index.byId.get(id);
+    return el !== void 0 && markOf(el) !== null;
+  };
+  const viewFor = (el) => {
+    const out2 = index.out.get(el.id) ?? [];
+    const gone = out2.filter((l) => withheld(l.id));
+    if (!gone.length && !(index.inn.get(el.id) ?? []).some((l) => withheld(l.id))) return index;
+    return {
+      ...index,
+      out: /* @__PURE__ */ new Map([[el.id, out2.filter((l) => !withheld(l.id))]]),
+      inn: /* @__PURE__ */ new Map([[el.id, (index.inn.get(el.id) ?? []).filter((l) => !withheld(l.id))]]),
+      unresolved: /* @__PURE__ */ new Map([[el.id, [...index.unresolved.get(el.id) ?? [], ...gone]]])
+    };
+  };
+  const out = { context: [], kept: [], dropped: [], truncated: [], leftOut: { proposed: [], hidden: [], room: [] } };
   let total = 0;
   let full = false;
   for (const item of items) {
     const el = item && typeof item === "object" && "element" in item ? item.element : item;
+    const mark = markOf(el);
+    if (mark) {
+      out.leftOut[mark].push(el.id);
+      continue;
+    }
     if (full || out.context.length >= ASK_LIMITS.itemsMax) {
       out.dropped.push(el.id);
       continue;
     }
-    let text = renderElement(el, index);
+    let text = renderElement(el, viewFor(el));
+    if (isProposed(el)) text = `[${REVIEW_PROPOSED_LABEL}] ${text}`;
     if (chars(text) > ASK_LIMITS.itemMax) {
       text = cut(text, ASK_LIMITS.itemMax);
       out.truncated.push(el.id);
@@ -4889,6 +4931,7 @@ export {
   PHOTO_MAX_BYTES,
   PHOTO_TYPES,
   PUBLIC_FIELDS,
+  REVIEW_PROPOSED_LABEL,
   ROOM_PAIRS,
   SPATIAL_TYPES,
   TokenResource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.71.0",
+  "version": "4.72.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {