@bitmagic/world-forger 0.1.43-dev.5 → 0.1.43-dev.7

package/dist/engine-asset-urls.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Expanding `engine-asset:` URLs to absolute ones, for the Bitmagic writers.
+ *
+ * A template may name an engine-shipped file as `engine-asset:<path>` (W5.6, decision H-c): the
+ * engine resolves it at load time against the active hosting's `contentBaseUrl`, so one template
+ * serves every hosting provider. Bitmagic's own writers — the CLI's `init`/`upgrade`/`import` and
+ * the agent's template import and switch — do not keep the scheme (decision H-d): they expand it
+ * to the Bitmagic content base when they copy a template, so a Bitmagic `world.json`/`game.json`
+ * stays byte-identical to what it was before the scheme existed and every offline reader (Creator
+ * previews, the agent's world inspection, the CLI's URL collectors, the api-server thumbnails)
+ * keeps seeing absolute URLs. See docs/engine-open-source-audit/plans/W5.6-hosting.md §2.3.
+ *
+ * The scheme string is repeated here on purpose: the engine's `ENGINE_ASSET_SCHEME`
+ * (game/src/engine/runtime/hosting.ts) cannot be imported by a shared package. The two are held
+ * equal by game/src/bitmagic/__tests__/TemplateExpansion.test.ts.
+ */
+/** The prefix that marks a URL as relative to the hosting's content root. */
+export declare const ENGINE_ASSET_URL_SCHEME = "engine-asset:";
+/**
+ * `url` with the scheme replaced by `base`, or `url` itself when it does not carry the scheme.
+ * The same rule as the engine's `resolveEngineAssetUrl`: leading slashes of the path are dropped
+ * and a `/` is supplied when `base` lacks one, so a writer's expansion and the engine's load-time
+ * resolution always give the same URL (held by TemplateExpansion.test.ts).
+ */
+export declare function expandEngineAssetUrl(url: string, base: string): string;
+/**
+ * Every string anywhere in `value` (object values and array items, at any depth — never object
+ * keys) that starts with `engine-asset:` expanded by {@link expandEngineAssetUrl}. `base` is a
+ * content root, e.g. `BITMAGIC_ENGINE_CONTENT_BASE` from `@bitmagic/asset-core/engine-content`.
+ *
+ * Pure and copy-on-write: what changes is copied along the path to it, everything else is shared,
+ * and when nothing matches the SAME value comes back (`===`), so a caller can tell "nothing to
+ * write" from the identity alone.
+ */
+export declare function expandEngineAssetUrls<T>(value: T, base: string): T;
+/**
+ * The JSON document in `text` with its `engine-asset:` URLs expanded, for a writer that copies a
+ * template's `world.json`/`game.json` as text.
+ *
+ * `text` itself comes back — byte for byte — when the document has nothing to expand (including
+ * text that is not JSON: a writer copying a file is not the place to reject it). Otherwise the
+ * document is re-serialized with two-space indentation, keeping a trailing newline if the input
+ * had one, which is the format every template under templates/ is already in; so expanding a
+ * template whose URLs were converted to the scheme gives back exactly the file it was converted
+ * from.
+ */
+export declare function expandEngineAssetUrlsInJsonText(text: string, base: string): string;
+//# sourceMappingURL=engine-asset-urls.d.ts.map

package/dist/engine-asset-urls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-asset-urls.d.ts","sourceRoot":"","sources":["../src/engine-asset-urls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAItE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAElE;AAuCD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAWlF"}

package/dist/engine-asset-urls.js

@@ -0,0 +1,106 @@
+/**
+ * Expanding `engine-asset:` URLs to absolute ones, for the Bitmagic writers.
+ *
+ * A template may name an engine-shipped file as `engine-asset:<path>` (W5.6, decision H-c): the
+ * engine resolves it at load time against the active hosting's `contentBaseUrl`, so one template
+ * serves every hosting provider. Bitmagic's own writers — the CLI's `init`/`upgrade`/`import` and
+ * the agent's template import and switch — do not keep the scheme (decision H-d): they expand it
+ * to the Bitmagic content base when they copy a template, so a Bitmagic `world.json`/`game.json`
+ * stays byte-identical to what it was before the scheme existed and every offline reader (Creator
+ * previews, the agent's world inspection, the CLI's URL collectors, the api-server thumbnails)
+ * keeps seeing absolute URLs. See docs/engine-open-source-audit/plans/W5.6-hosting.md §2.3.
+ *
+ * The scheme string is repeated here on purpose: the engine's `ENGINE_ASSET_SCHEME`
+ * (game/src/engine/runtime/hosting.ts) cannot be imported by a shared package. The two are held
+ * equal by game/src/bitmagic/__tests__/TemplateExpansion.test.ts.
+ */
+/** The prefix that marks a URL as relative to the hosting's content root. */
+export const ENGINE_ASSET_URL_SCHEME = 'engine-asset:';
+/**
+ * `url` with the scheme replaced by `base`, or `url` itself when it does not carry the scheme.
+ * The same rule as the engine's `resolveEngineAssetUrl`: leading slashes of the path are dropped
+ * and a `/` is supplied when `base` lacks one, so a writer's expansion and the engine's load-time
+ * resolution always give the same URL (held by TemplateExpansion.test.ts).
+ */
+export function expandEngineAssetUrl(url, base) {
+    if (!url.startsWith(ENGINE_ASSET_URL_SCHEME))
+        return url;
+    const rest = url.slice(ENGINE_ASSET_URL_SCHEME.length).replace(/^\/+/, '');
+    return `${base.endsWith('/') ? base : `${base}/`}${rest}`;
+}
+/**
+ * Every string anywhere in `value` (object values and array items, at any depth — never object
+ * keys) that starts with `engine-asset:` expanded by {@link expandEngineAssetUrl}. `base` is a
+ * content root, e.g. `BITMAGIC_ENGINE_CONTENT_BASE` from `@bitmagic/asset-core/engine-content`.
+ *
+ * Pure and copy-on-write: what changes is copied along the path to it, everything else is shared,
+ * and when nothing matches the SAME value comes back (`===`), so a caller can tell "nothing to
+ * write" from the identity alone.
+ */
+export function expandEngineAssetUrls(value, base) {
+    return expandValue(value, base);
+}
+function expandValue(value, base) {
+    if (typeof value === 'string')
+        return expandEngineAssetUrl(value, base);
+    if (Array.isArray(value)) {
+        let out = null;
+        for (let i = 0; i < value.length; i++) {
+            const item = value[i];
+            const next = expandValue(item, base);
+            if (next !== item) {
+                out ?? (out = value.slice());
+                out[i] = next;
+            }
+        }
+        return out ?? value;
+    }
+    if (isPlainObject(value)) {
+        let out = null;
+        for (const key of Object.keys(value)) {
+            const item = value[key];
+            const next = expandValue(item, base);
+            if (next !== item) {
+                out ?? (out = { ...value });
+                // defineProperty, not assignment: JSON.parse makes `__proto__` an own key, and assigning
+                // to it would set the copy's prototype instead of the value.
+                Object.defineProperty(out, key, { value: next, writable: true, enumerable: true, configurable: true });
+            }
+        }
+        return out ?? value;
+    }
+    return value;
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * The JSON document in `text` with its `engine-asset:` URLs expanded, for a writer that copies a
+ * template's `world.json`/`game.json` as text.
+ *
+ * `text` itself comes back — byte for byte — when the document has nothing to expand (including
+ * text that is not JSON: a writer copying a file is not the place to reject it). Otherwise the
+ * document is re-serialized with two-space indentation, keeping a trailing newline if the input
+ * had one, which is the format every template under templates/ is already in; so expanding a
+ * template whose URLs were converted to the scheme gives back exactly the file it was converted
+ * from.
+ */
+export function expandEngineAssetUrlsInJsonText(text, base) {
+    if (!text.includes(ENGINE_ASSET_URL_SCHEME))
+        return text;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+    const expanded = expandEngineAssetUrls(parsed, base);
+    if (expanded === parsed)
+        return text;
+    return `${JSON.stringify(expanded, null, 2)}${text.endsWith('\n') ? '\n' : ''}`;
+}
+//# sourceMappingURL=engine-asset-urls.js.map

package/dist/engine-asset-urls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-asset-urls.js","sourceRoot":"","sources":["../src/engine-asset-urls.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -24,6 +24,7 @@
  */
 export * from './artifact-types.js';
 export * from './forge-constants.js';
+export * from './engine-asset-urls.js';
 export * from './physics-mode.js';
 export * from './terrain-height-grid.js';
 export * from './world-json-strict-validator.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -24,6 +24,7 @@
  */
 export * from './artifact-types.js';
 export * from './forge-constants.js';
+export * from './engine-asset-urls.js';
 export * from './physics-mode.js';
 export * from './terrain-height-grid.js';
 export * from './world-json-strict-validator.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,4BAA4B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitmagic/world-forger",
-  "version": "0.1.43-dev.5",
+  "version": "0.1.43-dev.7",
   "description": "Client half of the Bitmagic world forger: the forged-level artifact schema, the host seams, and the browser pipeline steps that bake archetypes, bake a level and place its instances.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "Bitmagic Oy",