@onlyworlds/sdk 4.69.0 → 4.70.0

package/AGENTS.md

@@ -94,6 +94,9 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   first, UTF-8 name order, 1980 stamps) and holds only `world.json` and the folder's parts.
   Producers marked `"private": true` in `records/RECORDS.json` are left out whole unless
   `writeWorldFile(files, topDir, { includePrivateRecords: true })` (since 4.63.0; OW-8).
+  Element files marked `hidden: true` travel by default (a copy); a share passes
+  `{ includeHidden: false, report: r => r.hiddenLeftOut }` to leave them out whole and count
+  them (since 4.70.0; §4.8).
 - World calendars (since 4.20.0): `worldCalendars(elements)` finds the elements carrying
   `atlas_calendar` (Atlas owns the field: read it, never write it); `resolveCalendarLens` picks
   one; `formatStep(config, step)` names a point on the world's integer time line, `parseDate`

package/CHANGELOG.md

@@ -5,6 +5,18 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.70.0] - 2026-10-23
+
+### Added
+
+- **`writeWorldFile(files, topDir, { includeHidden: false })`** (folder spec §4.8, Skeld, OW Atlas h20 #11469): a world file is a copy, so an element file carrying the hidden mark travels byte for byte by default, as before. A tool making a file to hand to someone else passes `includeHidden: false`, and every `.json` file directly in a type folder of `elements/` or the legacy `spatial/` whose JSON has a top-level `hidden` (anything but absent, `null` or `false`, so `"true"` and `1` count, as the Python package's `is_hidden`) is left out whole. A file there that is not UTF-8 JSON, or not an object, is kept. Nothing else is rewritten: a visible element's link to a hidden one keeps its id. The two defaults differ on purpose: private records out unless asked, hidden kept unless the write is a share.
+- **`report: (r: OwWriteWorldFileReport) => void`**, a `writeWorldFile` option: called once with `{ hiddenLeftOut }` after the archive is made and before it is returned, never on a refusal. The return stays the bytes. An `includeHidden` that is not a boolean, or a `report` that is not a function, is a `TypeError` before anything is written; both keys join the options fence.
+
+### Fixed
+
+- **`draught`'s doc comment names `compact`** (4.69.0, keel #585), so the docs' generated reference row carries it.
+- Tests: a hidden element file byte-identical by default and with `includeHidden: true`, the report 0; left out as a share, the report 1, every other file byte-identical; the legacy layout, `.JSON`, and a doubtful mark left out; not JSON, not UTF-8, not an object, a null or nested mark, a deeper file, a non-JSON file and the other parts kept; the same bytes for the same files either way; the report not called on a refusal; the fence. Watched failing with the leave-out turned into a keep (3 tests red), restored. The 85-case `.owworld` set unchanged.
+
 ## [4.69.0] - 2026-10-23
 
 ### Added

package/README.md

@@ -299,6 +299,15 @@ The writer gives the same bytes for the same files: the `mimetype` marker first,
 
 `records/` travels byte for byte, except a producer's directory that `records/RECORDS.json` marks `"private": true`: that one is left out whole, and `RECORDS.json` itself travels unchanged, so the reader can see a producer was left out. Pass `writeWorldFile(files, topDir, { includePrivateRecords: true })` to carry private records too. A `RECORDS.json` that is not a JSON array of objects is refused with a `TypeError` unless you pass that option, since the writer cannot tell which records are private.
 
+An element file marked hidden (`"hidden": true` at the top of its JSON, spec §4.8) travels byte for byte by default: a world file is a copy, also of your own world. When the file is a share, made to hand to someone else, pass `includeHidden: false`: every hidden file under `elements/<type>/` (or the old `spatial/<type>/`) is left out whole, and `report` tells you how many. Nothing else changes: a visible element's link to a hidden one keeps its id. A file there that is not JSON is kept.
+
+```typescript
+let left = 0;
+const share = writeWorldFile(files, topDir, { includeHidden: false, report: r => { left = r.hiddenLeftOut; } });
+```
+
+The two defaults differ on purpose: private records stay out unless you ask, hidden elements stay in unless the write is a share.
+
 ## World calendars
 
 A world's time is an integer line (`time_range_current` is a point on it, and so is an Event's `start_date`). A calendar names its points: months, days, eras. Atlas keeps a calendar on an element (a Construct by convention) in its `atlas_calendar` field, and the SDK reads it with Atlas's own calendar code (since 4.20.0). Atlas owns that field and is its only writer; read it, never write it.

package/dist/index.d.ts

@@ -3644,7 +3644,9 @@ declare class OwV2Client {
      * Character they can see; a player seat or a guest for its own Character only (another id is
      * 404). `asOf` is a filter on the elements' own dates, not time travel. A `cut` that is not
      * empty means the serving is partial (`cut.proposed` also counts proposed elements left out because
-     * the component was not named). Served `Cache-Control: private, no-store`.
+     * the component was not named). `compact: true` leaves out every empty section and an empty `cut`,
+     * the frame and every null kept, answered as `OwDraughtCompact` (keel #585). Served
+     * `Cache-Control: private, no-store`.
      */
     draught(characterId: string, policy?: OwDraughtPolicy & {
         compact?: false;
@@ -4550,7 +4552,8 @@ declare function typeWord(world: object | null | undefined, type: string, opts?:
  * 1980-01-01 00:00, in the UTF-8 byte order of its name, JSON deflated and
  * everything else stored. `records/` travels whole and byte-exact, except the
  * producers `records/RECORDS.json` marks private, left out whole unless the
- * caller asks (OW-8, §4.5 rule 11).
+ * caller asks (OW-8, §4.5 rule 11). Element files marked hidden travel too,
+ * unless the caller says the file is a share (`includeHidden: false`, §4.8).
  *
  * A tool's own `.<tool>/` folder is the tool's (spec §4): the reader returns
  * it like any file (a caller leaves files out with `skip`), and the writer
@@ -4605,6 +4608,21 @@ interface OwWriteWorldFileOptions {
      * rule 11, OW-8). Left out or false, their directories are left out whole.
      */
     includePrivateRecords?: boolean;
+    /**
+     * Carry element files marked hidden (spec §4.8). Left out or true, they
+     * travel byte for byte: a world file is a copy. Pass false when the file is
+     * a share, made to hand to someone else: then every element file whose JSON
+     * carries the hidden mark is left out whole, and `report` counts them. The
+     * default is the opposite of `includePrivateRecords`'s on purpose.
+     */
+    includeHidden?: boolean;
+    /** Called once with what the write left out, after the archive is made and before it is returned; never on a refusal. */
+    report?: (report: OwWriteWorldFileReport) => void;
+}
+/** What `writeWorldFile` left out, handed to its `report` option. */
+interface OwWriteWorldFileReport {
+    /** Element files left out for the hidden mark (`includeHidden: false`); 0 otherwise. */
+    hiddenLeftOut: number;
 }
 /**
  * Write a world file under one top-level folder `topDir`: the `mimetype`
@@ -4624,8 +4642,19 @@ interface OwWriteWorldFileOptions {
  * to carry them; then the manifest is not read and every record travels. No
  * manifest, nothing is private.
  *
+ * Element files marked hidden (spec §4.8) travel byte for byte by default: a
+ * world file is a copy, also of a person's own world. A share is the offering
+ * tool's question: pass `{ includeHidden: false }` for a file made to hand to
+ * someone else, and every element file under `elements/<type>/` or
+ * `spatial/<type>/` whose JSON carries a top-level `hidden` (anything but
+ * absent, `null` or `false`) is left out whole. A file there that is not
+ * JSON is kept. Nothing else is rewritten: a visible element's link to a
+ * hidden one keeps its id, which then names no file. Pass
+ * `report: r => …` to learn `r.hiddenLeftOut`, the count left out.
+ *
  * Throws a `TypeError`, having written nothing, for an unknown option, an
- * `includePrivateRecords` that is not a boolean, and (unless private records
+ * `includePrivateRecords` or `includeHidden` that is not a boolean, a
+ * `report` that is not a function, and (unless private records
  * are asked for) a `RECORDS.json` that is not a JSON array of objects or that
  * marks an entry private without a producer name. Refuses (`OwWorldFileError`)
  * an unsafe path or `topDir`, a duplicate path, a name some disk cannot hold,
@@ -5444,4 +5473,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, 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, 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 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, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -3350,17 +3350,36 @@ function carried(path) {
   return !segs.some((s) => s.startsWith(".")) && !path.endsWith(".meta");
 }
 var STAMP = new Date(1980, 0, 1, 0, 0, 0);
-var WRITE_OPTION_KEYS = ["includePrivateRecords"];
+var WRITE_OPTION_KEYS = ["includePrivateRecords", "includeHidden", "report"];
 var RECORDS_MANIFEST = "records/RECORDS.json";
-function asksPrivate(opts) {
-  if (opts === void 0 || opts === null) return false;
+function writeOptions(opts) {
+  if (opts === void 0 || opts === null) return { includePrivate: false, includeHidden: true };
   if (typeof opts !== "object") throw new TypeError(`writeWorldFile: options must be an object, such as { includePrivateRecords: true }. Nothing was written.`);
   refuseUnknownOptions("writeWorldFile", opts, WRITE_OPTION_KEYS, "Nothing was written.");
-  const asked = opts.includePrivateRecords;
-  if (asked !== void 0 && typeof asked !== "boolean") {
-    throw new TypeError(`writeWorldFile: includePrivateRecords must be true or false; got ${JSON.stringify(asked) ?? String(asked)}. Nothing was written.`);
+  const o = opts;
+  for (const key of ["includePrivateRecords", "includeHidden"]) {
+    const asked = o[key];
+    if (asked !== void 0 && typeof asked !== "boolean") {
+      throw new TypeError(`writeWorldFile: ${key} must be true or false; got ${JSON.stringify(asked) ?? String(asked)}. Nothing was written.`);
+    }
+  }
+  if (o.report !== void 0 && typeof o.report !== "function") {
+    throw new TypeError(`writeWorldFile: report must be a function; got ${JSON.stringify(o.report) ?? String(o.report)}. Nothing was written.`);
+  }
+  return { includePrivate: o.includePrivateRecords === true, includeHidden: o.includeHidden !== false, report: o.report };
+}
+function isHiddenElement(f) {
+  const segs = f.path.split("/");
+  if (segs.length !== 3 || segs[0] !== "elements" && segs[0] !== "spatial" || !/\.json$/i.test(segs[2])) return false;
+  let doc;
+  try {
+    doc = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(f.data));
+  } catch {
+    return false;
   }
-  return asked === true;
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return false;
+  const mark = doc.hidden;
+  return mark !== void 0 && mark !== null && mark !== false;
 }
 function privateProducers(files) {
   const manifest = files.find((f) => f.path === RECORDS_MANIFEST);
@@ -3386,7 +3405,7 @@ function privateProducers(files) {
   return out;
 }
 function writeWorldFile(files, topDir, opts = {}) {
-  const includePrivate = asksPrivate(opts);
+  const { includePrivate, includeHidden, report } = writeOptions(opts);
   if (pathFault(topDir) || topDir.includes("/")) throw new OwWorldFileError("unsafe_path");
   const seen = /* @__PURE__ */ new Set();
   for (const f of files) {
@@ -3399,7 +3418,15 @@ function writeWorldFile(files, topDir, opts = {}) {
     const segs = path.split("/");
     return segs.length > 2 && segs[0] === "records" && left.has(foldName(segs[1]));
   };
-  const kept = files.filter((f) => carried(f.path) && !inPrivate(f.path));
+  let hiddenLeftOut = 0;
+  const kept = files.filter((f) => {
+    if (!carried(f.path) || inPrivate(f.path)) return false;
+    if (!includeHidden && isHiddenElement(f)) {
+      hiddenLeftOut++;
+      return false;
+    }
+    return true;
+  });
   if (!kept.some((f) => f.path === WORLD_FILE)) throw new OwWorldFileError("not_a_world");
   const keys = kept.map((f) => `${topDir}/${f.path}`);
   for (const key of keys) {
@@ -3416,7 +3443,9 @@ function writeWorldFile(files, topDir, opts = {}) {
     if (f.path === WORLD_FILE) data = withoutLink(data, parseWorld(data)).data;
     input[`${topDir}/${f.path}`] = [data, { level: /\.json$/i.test(f.path) ? 6 : 0, mtime: STAMP }];
   }
-  return zipSync(input);
+  const zip = zipSync(input);
+  report?.({ hiddenLeftOut });
+  return zip;
 }
 
 // src/room.ts

package/package.json

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