@godot-scene-web/project 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomás Fox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/fetch.d.ts

@@ -0,0 +1,147 @@
+import { t as GodotProjectResolvedResource } from "./shared-Dgi2oc_H.js";
+import { GodotExtResource, GodotNode, GodotResource, GodotResourceRefValue, GodotSceneState, GodotVariant } from "@godot-scene-web/core";
+
+//#region src/fetch.d.ts
+type GodotFetchCacheSnapshot<T> = {
+  status: "ready";
+  path: string;
+  value: T;
+} | {
+  status: "pending";
+  path: string;
+  promise: Promise<T>;
+} | {
+  status: "error";
+  path: string;
+  message: string;
+  error: unknown;
+};
+interface GodotFetchDocumentCache<T> {
+  peek: (resourcePath: string) => GodotFetchCacheSnapshot<T> | undefined;
+  load: (resourcePath: string) => Promise<T>;
+  preload: (resourcePath: string) => Promise<void>;
+  subscribe: (listener: () => void) => () => void;
+}
+interface GodotFetchProjectResolverOptions {
+  assetBaseUrl?: string | ((resourcePath: string) => string);
+  fetch?: (input: string) => Promise<Pick<Response, "ok" | "status" | "text">>;
+  /**
+   * Transitive prefetch: the moment a scene/resource document parses, kick loads
+   * for every `.tscn`/`.tres`/`.res` it references, so a tree's dependencies fan
+   * out level-parallel instead of being discovered one consumer render at a time.
+   * Off by default — lazy consumers rely on hidden external scenes NOT fetching.
+   */
+  preloadDependencies?: boolean;
+  /**
+   * Intrinsic pixel size for a direct image resource (a `Texture2D` ExtResource
+   * pointing at a `.png`/`.webp`/…), from host asset metadata (captured/extracted).
+   * Used so `NinePatchRect` 9-slice margins that exceed the texture (event_button.png:
+   * 284px wide, 192px L/R margins) clamp to the source the way Godot does, and so a
+   * `Sprite2D` box can size to its texture. Return `undefined` when unknown — in a
+   * browser the resolver then falls back to measuring the decoded image itself (see
+   * the `imageSizes` cache); outside a browser the texture resolves without a size,
+   * as before.
+   */
+  resourceSize?: (resourcePath: string) => {
+    width: number;
+    height: number;
+  } | undefined;
+  /**
+   * Crop an AtlasTexture sprite (a region of a larger atlas page) into a standalone
+   * image, returning a usable URL (e.g. a `blob:`/`data:` URL the host produced with a
+   * canvas). Used ONLY when the atlas page resolves to an EXTERNAL url (not a `data:`
+   * URL): the renderer's built-in SVG crop embeds the atlas via `<image href>`, which
+   * browsers block for external refs inside CSS-image SVGs, and CSS `border-image`
+   * cannot 9-slice a sub-region of an atlas — so a NinePatch atlas sprite over an
+   * external atlas can't be cropped in pure CSS. The host fetches each atlas page ONCE
+   * (cached) and crops regions on a canvas, so the page is reused across its sprites.
+   * Async: the result settles through the resolver's cache like any other resource, so
+   * the consumer re-renders when the crop is ready. Absent ⇒ unchanged behavior (the
+   * sprite keeps its embedded-SVG crop / CSS-offset fallback), so goldens and hosts that
+   * pre-crop server-side are byte-identical.
+   */
+  cropAtlasRegion?: (atlasUrl: string, region: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }, margin: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }) => Promise<string>;
+}
+interface GodotFetchExternalSceneResolveContext {
+  ref: GodotResourceRefValue;
+  node: GodotNode;
+  nodePath: string;
+  props: Record<string, GodotVariant>;
+}
+interface GodotFetchProjectSceneOptions {
+  resolveExternalScene: (context: GodotFetchExternalSceneResolveContext) => GodotSceneState | {
+    status: "ready";
+    scene: GodotSceneState;
+    path?: string;
+  } | {
+    status: "pending";
+    path?: string;
+    message?: string;
+  } | {
+    status: "error";
+    path?: string;
+    message: string;
+  } | undefined;
+  resolveResource: (ref: GodotResourceRefValue, node: GodotNode) => GodotProjectResolvedResource | undefined;
+  resolveResourcePath: (path: string, node: GodotNode) => GodotProjectResolvedResource | undefined;
+  /**
+   * Resolve a theme item (e.g. a font size) for a node from its assigned `theme`
+   * resource, following Godot's type-variation -> type -> default cascade. Optional:
+   * absent ⇒ the renderer keeps its built-in fallbacks (the prior behavior). The HTML
+   * renderer calls this for `font_size`/`normal_font_size`/… when a node carries no
+   * inline `theme_override_font_sizes/*`.
+   */
+  resolveTheme?: (node: GodotNode, name: string) => GodotVariant | undefined;
+}
+interface GodotFetchProjectResolver {
+  resourcePathToUrl: (resourcePath: string) => string;
+  scenes: GodotFetchDocumentCache<GodotSceneState>;
+  resources: GodotFetchDocumentCache<GodotResource>;
+  peekScene: (resourcePath: string) => GodotFetchCacheSnapshot<GodotSceneState> | undefined;
+  loadScene: (resourcePath: string) => Promise<GodotSceneState>;
+  preload: (resourcePath: string) => Promise<void>;
+  subscribe: (listener: () => void) => () => void;
+  extResource: (scene: GodotSceneState, ref: GodotResourceRefValue) => GodotExtResource | undefined;
+  resolveResource: (scene: GodotSceneState, ref: GodotResourceRefValue, node?: GodotNode) => GodotProjectResolvedResource | undefined;
+  resolveResourcePath: (resourcePath: string, type?: string) => GodotProjectResolvedResource | undefined;
+  resolveExternalScene: (scene: GodotSceneState, ref: GodotResourceRefValue, node?: GodotNode) => GodotSceneState | {
+    status: "ready";
+    scene: GodotSceneState;
+    path?: string;
+  } | {
+    status: "pending";
+    path?: string;
+    message?: string;
+  } | {
+    status: "error";
+    path?: string;
+    message: string;
+  } | undefined;
+  sceneOptions: (scene: GodotSceneState) => GodotFetchProjectSceneOptions;
+  /**
+   * Monotonic settle counters, one per document cache. A consumer can use them
+   * for cache-state-keyed memoization: scene-graph derivation depends on scene
+   * documents but never on `.tres` resource content, so a derive memo stays
+   * valid while `scenes` is unchanged even as `resources` advances.
+   */
+  generations: () => {
+    scenes: number;
+    resources: number;
+    croppedAtlas: number;
+    imageSizes: number;
+  };
+}
+declare function createGodotFetchProjectResolver(options?: GodotFetchProjectResolverOptions): GodotFetchProjectResolver;
+//#endregion
+export { GodotFetchCacheSnapshot, GodotFetchDocumentCache, GodotFetchExternalSceneResolveContext, GodotFetchProjectResolver, GodotFetchProjectResolverOptions, GodotFetchProjectSceneOptions, type GodotProjectResolvedResource, createGodotFetchProjectResolver };
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","names":[],"sources":["../src/fetch.ts"],"mappings":";;;;KAiEY,uBAAA;EACN,MAAA;EAAiB,IAAA;EAAc,KAAA,EAAO,CAAA;AAAA;EACtC,MAAA;EAAmB,IAAA;EAAc,OAAA,EAAS,OAAA,CAAQ,CAAA;AAAA;EAClD,MAAA;EAAiB,IAAA;EAAc,OAAA;EAAiB,KAAA;AAAA;AAAA,UAErC,uBAAA;EACf,IAAA,GAAO,YAAA,aAAyB,uBAAA,CAAwB,CAAA;EACxD,IAAA,GAAO,YAAA,aAAyB,OAAA,CAAQ,CAAA;EACxC,OAAA,GAAU,YAAA,aAAyB,OAAA;EACnC,SAAA,GAAY,QAAA;AAAA;AAAA,UAGG,gCAAA;EACf,YAAA,cAA0B,YAAA;EAC1B,KAAA,IAAS,KAAA,aAAkB,OAAA,CAAQ,IAAA,CAAK,QAAA;EAXiB;AAAA;AAE3D;;;;EAgBE,mBAAA;EAdwC;;;;;;;;;;EAyBxC,YAAA,IACE,YAAA;IACK,KAAA;IAAe,MAAA;EAAA;EA1BtB;;;;;;AACgC;AAGlC;;;;;;;EAqCE,eAAA,IACE,QAAA,UACA,MAAA;IAAU,CAAA;IAAW,CAAA;IAAW,KAAA;IAAe,MAAA;EAAA,GAC/C,MAAA;IAAU,CAAA;IAAW,CAAA;IAAW,KAAA;IAAe,MAAA;EAAA,MAC5C,OAAA;AAAA;AAAA,UAGU,qCAAA;EACf,GAAA,EAAK,qBAAA;EACL,IAAA,EAAM,SAAA;EACN,QAAA;EACA,KAAA,EAAO,MAAA,SAAe,YAAA;AAAA;AAAA,UAGP,6BAAA;EACf,oBAAA,GACE,OAAA,EAAS,qCAAA,KAEP,eAAA;IACE,MAAA;IAAiB,KAAA,EAAO,eAAA;IAAiB,IAAA;EAAA;IACzC,MAAA;IAAmB,IAAA;IAAe,OAAA;EAAA;IAClC,MAAA;IAAiB,IAAA;IAAe,OAAA;EAAA;EAEtC,eAAA,GACE,GAAA,EAAK,qBAAA,EACL,IAAA,EAAM,SAAA,KACH,4BAAA;EACL,mBAAA,GACE,IAAA,UACA,IAAA,EAAM,SAAA,KACH,4BAAA;EAnBiB;;;;;;;EA2BtB,YAAA,IAAgB,IAAA,EAAM,SAAA,EAAW,IAAA,aAAiB,YAAA;AAAA;AAAA,UAGnC,yBAAA;EACf,iBAAA,GAAoB,YAAA;EACpB,MAAA,EAAQ,uBAAA,CAAwB,eAAA;EAChC,SAAA,EAAW,uBAAA,CAAwB,aAAA;EACnC,SAAA,GACE,YAAA,aACG,uBAAA,CAAwB,eAAA;EAC7B,SAAA,GAAY,YAAA,aAAyB,OAAA,CAAQ,eAAA;EAC7C,OAAA,GAAU,YAAA,aAAyB,OAAA;EACnC,SAAA,GAAY,QAAA;EACZ,WAAA,GACE,KAAA,EAAO,eAAA,EACP,GAAA,EAAK,qBAAA,KACF,gBAAA;EACL,eAAA,GACE,KAAA,EAAO,eAAA,EACP,GAAA,EAAK,qBAAA,EACL,IAAA,GAAO,SAAA,KACJ,4BAAA;EACL,mBAAA,GACE,YAAA,UACA,IAAA,cACG,4BAAA;EACL,oBAAA,GACE,KAAA,EAAO,eAAA,EACP,GAAA,EAAK,qBAAA,EACL,IAAA,GAAO,SAAA,KAEL,eAAA;IACE,MAAA;IAAiB,KAAA,EAAO,eAAA;IAAiB,IAAA;EAAA;IACzC,MAAA;IAAmB,IAAA;IAAe,OAAA;EAAA;IAClC,MAAA;IAAiB,IAAA;IAAe,OAAA;EAAA;EAEtC,YAAA,GAAe,KAAA,EAAO,eAAA,KAAoB,6BAAA;EAvDnB;;;;;;EA8DvB,WAAA;IACE,MAAA;IACA,SAAA;IACA,YAAA;IACA,UAAA;EAAA;AAAA;AAAA,iBAIY,+BAAA,CACd,OAAA,GAAS,gCAAA,GACR,yBAAyB"}