@playabl/sdk 1.1.0-beta.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,14 +8,7 @@ Browser SDK for Playabl games providing parent-platform communication, game stat
8
8
  npm install @playabl/sdk
9
9
  ```
10
10
 
11
- While 1.1.0 is in beta the stable tag still resolves to 1.0.0; `@playabl/sdk/layout` and
12
- the layout types are on the `beta` dist-tag:
13
-
14
- ```bash
15
- npm install @playabl/sdk@beta
16
- ```
17
-
18
- `sdk.game` and `sdk.devtools` need runtime 1.0.0 or newer in the environment the game loads from. That runtime is live on dev, staging and production.
11
+ `sdk.game` and `sdk.devtools` need runtime 1.0.0 or newer in the environment the game loads from. That runtime is live on dev, staging and production. What 1.1.0 adds needs runtime 1.6.0 or newer there.
19
12
 
20
13
  ## Usage
21
14
 
@@ -194,6 +187,12 @@ const { items, entries } = synthesiseLayout(layout, tweaksSchema, {}, DEFAULT_FR
194
187
 
195
188
  It is an ES module: `import` loads it anywhere, and `require()` on Node 20.19+ or 22.12+. TypeScript finds its types with `moduleResolution` set to `node16`, `nodenext` or `bundler` in an ES module project, and only with `nodenext` (TypeScript 5.8 or newer) in a CommonJS one; `node10` does not read `exports`, so it is not supported. Besides `synthesiseLayout` and `DEFAULT_FRAME`, it exports the role table (`LAYOUT_ROLES`, `LAYOUT_ANCHORS`, `LAYOUT_WEIGHTS`, `LAYOUT_ALIGNS`, `ENTRY_FIELDS`), `layoutKey`, `defaultPrefix` and `roleLimits`; every table is frozen.
196
189
 
190
+ ### Runtime resolution
191
+
192
+ Most games never configure the runtime. Call `configure({ runtimeUrl })` or `configure({ manifestUrl })` before any other SDK call to import a specific runtime build or read a specific manifest.
193
+
194
+ A page can instead name its environment's manifest in `window.__PLAYABL_MANIFEST_URL__`, set before any module script runs. The Playabl workspace preview does this: it is served from `localhost` but belongs to dev, staging or production, so without it the wrapper would take `localhost` for SDK development and import its build-time fallback runtime. The order is `configure({ runtimeUrl })`, `configure({ manifestUrl })`, a valid `?env=` on the game URL (`?env=local` keeps the fallback), the global, then the hostname. The global is used only when it is a string holding an `https:` URL on `cdn.playabl.ai`, `cdn-staging.playabl.ai` or `cdn-dev.playabl.ai` on the default port; any other value is ignored with one console warning. It needs 1.1.0-beta.1 or newer.
195
+
197
196
  ## API Surface
198
197
 
199
198
  - `sdk.ready()` - Connects to the Playabl parent iframe host.
package/dist/index.d.ts CHANGED
@@ -40,6 +40,7 @@ type CellGridHooks = Required<Pick<ContentHooks, 'blankLevel' | 'placeInLevel' |
40
40
  * coordinates or origins also refuse. Pure and synchronous, as every content
41
41
  * hook must be; nothing here needs the runtime, so a game can call it while
42
42
  * building its vocabulary.
43
+ * A game that declares `describeScene().grid` with `cols`/`rows` needs none of this: the runtime's board profile (runtime 1.6.0+) supplies the three hooks itself; this helper stays for games on the raw-hook path.
43
44
  */
44
45
  declare function cellGridHooks({ cell, origin, key, }?: CellGridOptions): CellGridHooks;
45
46
 
@@ -476,11 +477,25 @@ interface ContentLevel {
476
477
  /** `lv_<n>` when minted by the engine; any non-empty string is tolerated from disk. */
477
478
  id: string;
478
479
  name: string;
479
- /** Names an entry in `ContentDocument.groups`. */
480
+ /** Names an entry in `ContentDocument.groups`. Absent only on a level a file had before every level had to be in a group; the engine never makes one (PLA-1849). */
480
481
  group?: string;
481
482
  owner: ContentOwner;
482
483
  /** Opaque to the engine: a plain JSON object or array. */
483
484
  payload: Record<string, unknown> | unknown[];
485
+ /**
486
+ * Present while the game's `acceptPayload` refuses this level's payload:
487
+ * the verdict taken right after the engine's last edit of it. Always last.
488
+ */
489
+ refusal?: LevelRefusal;
490
+ }
491
+ /**
492
+ * A level `acceptPayload` refused after an edit (PLA-1842). The edit stands;
493
+ * the mark says the level is not playable as it is. `reason` is the game's,
494
+ * one line of at most 200 UTF-16 code units, absent when it gave none.
495
+ * Runtime 1.4.5 or newer.
496
+ */
497
+ interface LevelRefusal {
498
+ reason?: string;
484
499
  }
485
500
  interface ContentDocument {
486
501
  version: 1;
@@ -502,6 +517,13 @@ interface ContentFieldSpec {
502
517
  options?: string[];
503
518
  /** Informational only — never substituted for a missing payload key. */
504
519
  default?: number | string | boolean;
520
+ /**
521
+ * `text` only: a `def:` id with a drawable `layout.json` entry. The SDK
522
+ * writes the active level's value of this field into every element marked
523
+ * with that id. On `name` the value is `level.name`, and the spec is not
524
+ * listed in `catalog.content.fields`.
525
+ */
526
+ layout?: string;
505
527
  }
506
528
  type ContentFieldValue = string | number | boolean | null;
507
529
  /**
@@ -534,6 +556,27 @@ interface LevelPreview {
534
556
  rows: number;
535
557
  cells: LevelPreviewCell[];
536
558
  }
559
+ /** The two layers a placed instance can be on; two of one layer never share a cell. */
560
+ type BoardLayer = 'floor' | 'object';
561
+ /**
562
+ * One placed instance of a level on a board the runtime owns (a game whose
563
+ * `describeScene()` returns a `grid` with `cols` / `rows` and writes fewer
564
+ * than the three placement hooks — a hook the game wrote keeps its verb, and
565
+ * the runtime supplies the rest): `payload.instances[]`. `x` / `y` are the
566
+ * top-left cell; `w` / `h` are written only when they differ from the
567
+ * definition's `footprint`. Every other field is the game's and passes
568
+ * through every mutation untouched.
569
+ */
570
+ interface BoardInstance {
571
+ /** Minted by the runtime (`i_<n>`, unique in the level, never from its position), or whatever the file holds. */
572
+ id: string;
573
+ defId: string;
574
+ x: number;
575
+ y: number;
576
+ w?: number;
577
+ h?: number;
578
+ [field: string]: unknown;
579
+ }
537
580
  /** A uniform placement grid over `[x, y, x+w, y+h]`, in game CSS px. */
538
581
  interface SceneGrid {
539
582
  x: number;
@@ -543,6 +586,13 @@ interface SceneGrid {
543
586
  cols: number;
544
587
  rows: number;
545
588
  }
589
+ /**
590
+ * Why the runtime's own board refused `place` / `content-move-instance` /
591
+ * `content-remove-instance`: a cell already held by an instance of the same
592
+ * layer, a second instance of a `singleton` definition, or the last instance
593
+ * of a `required` one. A refusal for any other reason carries none.
594
+ */
595
+ type ContentRefusalCause = 'occupied' | 'singleton' | 'required';
546
596
  /** The level the game reports as current; placement targets its `id`. */
547
597
  interface StateLevel {
548
598
  id: string;
@@ -566,6 +616,13 @@ interface CatalogEntryBase {
566
616
  nodeKinds: string[];
567
617
  /** Basename only. */
568
618
  sprite?: string;
619
+ /**
620
+ * The `assets.json` key `sprite` was resolved through — set only when the
621
+ * builder's `sprite` option named a key, never for a file name. It may name
622
+ * a key `catalog.assets` does not list (a legacy video); fall back to
623
+ * `sprite` then.
624
+ */
625
+ assetId?: string;
569
626
  singleton: boolean;
570
627
  }
571
628
  interface CatalogLevel extends CatalogEntryBase {
@@ -577,6 +634,8 @@ interface CatalogLevel extends CatalogEntryBase {
577
634
  contentId?: string;
578
635
  /** `{ name, group, ...declared }`, engine-attached by `contentId` lookup; never from `catalog()`. */
579
636
  fields?: Record<string, ContentFieldValue>;
637
+ /** The document level's mark (PLA-1842), engine-attached by `contentId` lookup; never from `catalog()`. */
638
+ refusal?: LevelRefusal;
580
639
  preview?: LevelPreview;
581
640
  }
582
641
  type CatalogScreen = CatalogEntryBase;
@@ -590,12 +649,35 @@ interface CatalogDefinition extends CatalogEntryBase {
590
649
  layout?: LayoutRoleMap;
591
650
  /** Drag/drop into a level writes a durable instance through `content.hooks.placeInLevel`. */
592
651
  placeable?: 'content';
652
+ /**
653
+ * The cells a placed instance covers, `[w, h]`, positive integers. On the
654
+ * wire it is present on every `placeable: "content"` definition, resolved
655
+ * to `[1, 1]` when undeclared, and absent on every other.
656
+ */
657
+ footprint?: [number, number];
658
+ /**
659
+ * Which instances a placed instance may share cells with: two instances of
660
+ * one layer never overlap, an `object` may sit on a `floor`. Present on the
661
+ * wire for every placeable definition (`"object"` when undeclared).
662
+ */
663
+ layer?: BoardLayer;
664
+ /** Whether the Creator may resize an instance's footprint. Present on the wire for every placeable definition (`false` when undeclared). */
665
+ resizable?: boolean;
666
+ /** A level keeps at least one instance of this definition: removing the last refuses. Present on the wire for every placeable definition (`false` when undeclared). */
667
+ required?: boolean;
593
668
  /**
594
669
  * Buttons the Creator shows on this definition's card. On the wire every item
595
670
  * is checked and the array is never empty; the value `definition()` returns
596
671
  * is the author's array, unchecked.
597
672
  */
598
673
  actions?: CatalogEntryAction[];
674
+ /**
675
+ * The catalog screen this definition is drawn on: the one whose id its
676
+ * `def:screen-<screen id>-…` id continues, the longest such
677
+ * (`def:screen-<screen id>` itself included), or `null`. The runtime stamps
678
+ * it on every definition it sends, replacing any value the game gave.
679
+ */
680
+ screen?: string | null;
599
681
  }
600
682
  /**
601
683
  * A button the Creator shows on a definition's card that fires a game
@@ -630,12 +712,146 @@ interface SceneNode {
630
712
  instance: Record<string, unknown>;
631
713
  /** Top level only. Marks a placed content instance; equals the instance id the placement hooks returned. */
632
714
  contentId?: string;
715
+ /**
716
+ * SDK-stamped on an interface node the runtime derived from an element
717
+ * carrying `data-layout-instance`: the attribute's trimmed value, usually
718
+ * the content id of what the element shows, the node's id then being
719
+ * `<key>@<value>` (`def:hud-card@lv_3` carries `lv_3`). A game-supplied one
720
+ * is ignored. Never `contentId`, which marks a placed level piece.
721
+ */
722
+ instanceKey?: string;
723
+ /**
724
+ * SDK-stamped on a node whose definition a level field is bound to: spread
725
+ * it into `content-set-field { ...levelField, value }`. A game-supplied one
726
+ * is ignored.
727
+ */
728
+ levelField?: {
729
+ id: string;
730
+ field: string;
731
+ };
732
+ /**
733
+ * SDK-stamped on a node whose definition declares a `text` layout role, or
734
+ * has a level field bound to it, when the runtime could read the copy: how
735
+ * it is set on the page now. A game-supplied one is ignored. It needs a
736
+ * runtime with the scene text stamp.
737
+ */
738
+ text?: TextStyleStamp;
739
+ }
740
+ /**
741
+ * The type of the copy a scene node's element holds, read from the live DOM
742
+ * when the `scene` is sent. Every length is in game CSS px: the computed
743
+ * values untransformed, `box` in the space of the node's `rect`, so a host
744
+ * turns the first into rendered px with `scale`. None is sent for a holder that
745
+ * is rotated or skewed. Not carried, though each can move a line break:
746
+ * `text-wrap-style` (`balance`, `pretty`), `word-break`, `overflow-wrap`,
747
+ * `hyphens` and `font-variation-settings`; where the game sets one, a host that
748
+ * lays the copy out greedily can break lines elsewhere.
749
+ */
750
+ interface TextStyleStamp {
751
+ /** The computed `font-family`, verbatim: the game's own stack. */
752
+ fontFamily: string;
753
+ /**
754
+ * The first family of `fontFamily` the game document can actually render, as
755
+ * one CSS family token: a generic keyword (`system-ui`), a plain name
756
+ * (`PlayablProbe`) or a name in double quotes (`"Bree Serif"`). A host that
757
+ * has a face the game lacks, its own Inter, sets copy in this family so it
758
+ * wraps as the game's does. A family counts when this copy's characters are
759
+ * set differently in front of the stack after it than by that stack alone,
760
+ * in advance or in the shape of the glyphs, a web face as well as an
761
+ * installed one: an installed Arabic family with no Latin letters is named
762
+ * for Arabic copy, and skipped for Latin letters, though not for a space or
763
+ * digit it holds, which the game draws in the first family that has them.
764
+ * One that sets the copy as wide as the next family but draws other glyphs
765
+ * (a CJK face against a serif) is named, not the one after it, and a web
766
+ * face the game has not used, or whose unicode-range leaves the copy out, is
767
+ * skipped. One token cannot say that copy in two scripts is drawn in two
768
+ * families, and names the first. Absent when no family of the stack
769
+ * resolves, or a face of one that this copy needs (its weight, its style,
770
+ * the slice its characters fall in) is still loading; use `fontFamily` then.
771
+ */
772
+ renderedFamily?: string;
773
+ fontWeight: string;
774
+ fontStyle: string;
775
+ fontSizePx: number;
776
+ /**
777
+ * The line pitch: the computed `line-height` when it is a px length, else
778
+ * measured from the lines themselves (never from the holder's box, which can
779
+ * be taller than its copy).
780
+ */
781
+ lineHeightPx: number;
782
+ /** 0 when the computed value is `normal`, or a percentage the engine leaves unresolved. */
783
+ letterSpacingPx: number;
784
+ /** 0 when the computed value is `normal`, or a percentage the engine leaves unresolved. */
785
+ wordSpacingPx: number;
786
+ /**
787
+ * The computed `text-indent` of the block container the copy sits in, when it
788
+ * is a px length, else 0. An inline holder that shares its lines with other
789
+ * content carries 0: the indent acts on the block's first line, and the
790
+ * holder's place along it is already in `box.x`.
791
+ */
792
+ textIndentPx: number;
793
+ /** The computed `font-stretch`, verbatim. */
794
+ fontStretch: string;
795
+ /** The computed `font-kerning`, verbatim. */
796
+ fontKerning: string;
797
+ /** The computed `font-variant`, verbatim. */
798
+ fontVariant: string;
799
+ /** The computed `font-feature-settings`, verbatim: `normal` when there are none. */
800
+ fontFeatureSettings: string;
801
+ textTransform: string;
802
+ /**
803
+ * The computed `text-align` of the block container the copy sits in: for an
804
+ * inline holder, its block's, since the property acts on block containers.
805
+ */
806
+ textAlign: string;
807
+ direction: 'ltr' | 'rtl';
808
+ whiteSpace: string;
809
+ /** Line boxes the copy occupies now, at least 1. */
810
+ lines: number;
811
+ /**
812
+ * Whether copy typed here breaks onto a new line at `box.w` as it grows: the
813
+ * holder's `white-space` allows wrapping, and the copy either already
814
+ * occupies two lines or the box `box.x` and `box.w` come from has a width
815
+ * that does not follow its copy. That is a block-level box in flow, not
816
+ * floated and not a flex or grid item (past any `display: contents`
817
+ * wrapper), and, whatever its display and position, one measured wider than
818
+ * its one line of copy by more than 1px: an absolutely positioned box with a
819
+ * width, a stretched flex or grid item, a flex item that grows to its row. A
820
+ * box held as wide as its `min-width`, or one that shares its line with other
821
+ * content, is not counted. An inline-block, a float, an absolutely positioned
822
+ * box and a flex or grid item that sizes to its copy are as wide as it. A
823
+ * field that wraps only at `lines >= 2` scrolls sideways while a one-line
824
+ * title is typed.
825
+ */
826
+ wraps: boolean;
827
+ /**
828
+ * Where the copy sits, as `rect` is measured. `x` and `w` are the content
829
+ * box (border box less border and padding) of the holder, which wraps the
830
+ * copy; when the holder is `display: inline`, whose own box is the union of
831
+ * its line fragments, or `contents`, which has none, they are the content box
832
+ * of the nearest ancestor that is neither, the block its lines sit in, but
833
+ * only when the holder's words are all that is in those lines. Sharing them
834
+ * (words, an icon or image, `::before` or `::after` content), the copy starts
835
+ * partway along the line, so they are the span of the holder's own words.
836
+ * `y` and `h` are the copy's own line boxes, `lines` times `lineHeightPx`,
837
+ * even where the holder's box is taller than its copy or, for an inline
838
+ * holder, shorter than its line. `w` and `h` are at least 2: the runtime
839
+ * sends no stamp for a smaller box.
840
+ */
841
+ box: SceneRect;
842
+ /**
843
+ * Rendered size over layout size of the holder: 1 untransformed. Read on both
844
+ * sides; no stamp is sent when they disagree (a rotation or skew).
845
+ */
846
+ scale: number;
633
847
  }
634
848
  interface CatalogEntryOptions {
635
849
  tweakKeys?: string[];
636
850
  nodeKinds?: string[];
637
851
  /**
638
- * An `assets.json` key; resolved to a basename through the merged mapping.
852
+ * An `assets.json` key, resolved to a basename through the merged mapping
853
+ * and recorded as the entry's `assetId`; or a bare image file name, which
854
+ * gets no `assetId`. A value that is neither is dropped with a warning.
639
855
  * `| undefined` on purpose: authors write `sprite: spriteFor('KEY')`, and
640
856
  * `spriteFor` returns `undefined` for an unknown key — under
641
857
  * `exactOptionalPropertyTypes` that would otherwise be a type error.
@@ -657,10 +873,19 @@ interface CatalogDefinitionOptions extends CatalogEntryOptions {
657
873
  * here. Ignored without `sprite`; a path (`/` or `\`) is dropped with a warning.
658
874
  */
659
875
  spriteFrame?: string | undefined;
876
+ /** Defaults to `false` for a `placeable: 'content'` definition and `true` for any other. */
660
877
  singleton?: boolean;
661
878
  category?: CatalogCategory;
662
879
  layout?: LayoutRoleMap;
663
880
  placeable?: 'content';
881
+ /** Cells a placed instance covers; `[1, 1]` when omitted. Read only with `placeable: 'content'`. */
882
+ footprint?: [number, number] | undefined;
883
+ /** `'object'` when omitted. Read only with `placeable: 'content'`. */
884
+ layer?: BoardLayer | undefined;
885
+ /** `false` when omitted. Read only with `placeable: 'content'`. */
886
+ resizable?: boolean | undefined;
887
+ /** `false` when omitted. Read only with `placeable: 'content'`. */
888
+ required?: boolean | undefined;
664
889
  /**
665
890
  * Buttons the Creator shows on this definition's card — for an `effects`
666
891
  * definition, `[{ kind: 'preview', command: 'preview-splash' }]`. A malformed
@@ -736,12 +961,32 @@ interface ContentHooks {
736
961
  /**
737
962
  * Required for `content-set-payload` — the verb is advertised only when this
738
963
  * exists (D19), because the engine cannot judge a game's payload shape.
739
- * Runs against a clone of the proposed payload: `false` refuses; the hook
740
- * may normalize the clone in place; anything else accepts.
964
+ * Runs against a clone of the proposed payload: `false` refuses; a
965
+ * `PayloadRefusal` refuses and says why; the hook may normalize the clone in
966
+ * place; anything else accepts. A refusal's `reason`, or the message the hook
967
+ * threw, becomes the verb's `command-refused.reason`.
968
+ *
969
+ * It also judges every payload an accepted edit produces, and every level on
970
+ * intake (PLA-1842; runtime 1.4.5 or newer): a refusal there never refuses
971
+ * the edit, it marks the level `refusal`. That clone is discarded, so a hook
972
+ * that has to change it to accept it marks the level too, without a reason.
741
973
  */
742
974
  acceptPayload?(payload: unknown, meta: {
743
975
  id: string;
744
- }): boolean | void;
976
+ }): boolean | void | PayloadRefusal;
977
+ }
978
+ /**
979
+ * `acceptPayload`'s refusal with a reason: exactly `accept: false` and an
980
+ * optional string `reason`, as own data properties, in a new object (never
981
+ * the payload clone the hook was handed). Any other key makes it an ordinary
982
+ * return, which accepts. The reason is sent as one line of at most 200 UTF-16
983
+ * code units (control characters become spaces; longer text is cut with `…`);
984
+ * a `reason` that is not a string is ignored and reported. Runtime 1.4.3 or
985
+ * newer: an older runtime accepts the payload.
986
+ */
987
+ interface PayloadRefusal {
988
+ accept: false;
989
+ reason?: string;
745
990
  }
746
991
  /** `content: { document, hooks, fields }` on `devtools.js` — opt-in. */
747
992
  interface DevtoolsContent {
@@ -769,8 +1014,20 @@ interface DevtoolsVocabulary {
769
1014
  definitions?: CatalogDefinition[];
770
1015
  progression?: CatalogProgression;
771
1016
  };
1017
+ /**
1018
+ * What the runtime cannot see from the page: the `grid` and the objects drawn
1019
+ * on a canvas. Every element marked `data-layout` whose `layout.json` entry is
1020
+ * drawn on the page and names a catalog definition is derived by the runtime,
1021
+ * which owns its identity and rect: a node listed here for one leaves the
1022
+ * scene and contributes at most its `instance`. Optional for a game with such
1023
+ * an entry, which gets a scene of its interface without it. A runtime of
1024
+ * 1.4.8 or older derives nothing and reports only the nodes listed here.
1025
+ * `nodes` is optional for a game whose pieces the runtime's board places
1026
+ * (runtime 1.6.0+): `{ grid }` alone, with a well-formed grid, lists the
1027
+ * active level's instances; a malformed grid alone keeps the previous scene.
1028
+ */
772
1029
  describeScene?(): {
773
- nodes: SceneNode[];
1030
+ nodes?: SceneNode[];
774
1031
  grid?: SceneGrid;
775
1032
  };
776
1033
  describeInstance?(nodeId: string): Record<string, unknown> | null | undefined;
@@ -822,7 +1079,8 @@ type RuntimeLoader = () => Promise<PlayablSDK>;
822
1079
  /**
823
1080
  * Override runtime resolution. `runtimeUrl` imports a specific runtime build
824
1081
  * directly; `manifestUrl` points at a specific manifest. Both bypass the
825
- * automatic environment detection — useful for QA or self-hosting.
1082
+ * automatic environment detection and `window.__PLAYABL_MANIFEST_URL__` —
1083
+ * useful for QA or self-hosting.
826
1084
  */
827
1085
  declare function configure(options: {
828
1086
  runtimeUrl?: string;
@@ -835,4 +1093,4 @@ declare const __testing: {
835
1093
  setRuntimeLoader(loader: RuntimeLoader): void;
836
1094
  };
837
1095
 
838
- export { type AssetDescriptor, type AssetEntry, type AssetKind, type AssetOverride, type AssetRecipe, type AssetStatus, type AssetType, type AssetValueEntry, type AssetsMapping, type AssetsRegisterOptions, type AssetsUrlMap, type AssetsValues, type BooleanTweak, type CameraAPI, type CameraOptions, type CameraResult, type CatalogCategory, type CatalogContext, type CatalogDefinition, type CatalogDefinitionOptions, type CatalogEntryAction, type CatalogEntryBase, type CatalogEntryOptions, type CatalogLevel, type CatalogLevelOptions, type CatalogProgression, type CatalogScreen, type CellGridEntry, type CellGridHooks, type CellGridOptions, type ColorTweak, type ContentDocument, type ContentFieldSpec, type ContentFieldType, type ContentFieldValue, type ContentGroup, type ContentHandle, type ContentHooks, type ContentLevel, type ContentOwner, type ContentVerbType, type DevtoolsCommand, type DevtoolsContent, type DevtoolsHandle, type DevtoolsVocabulary, type EnumTweak, type ErrorCode, type FileSystemAPI, type FileSystemOptions, type FileSystemResult, type GameLoopHooks, type GameMode, type GameRunHandle, type GameRunOptions, type GeolocationAPI, type GeolocationOptions, type GeolocationResult, type HapticsAPI, type LayoutEntry, type LayoutFile, type LayoutRole, type LayoutRoleMap, type LayoutValues, type LevelPreview, type LevelPreviewCell, type MicrophoneAPI, type MicrophoneRecordOptions, type MicrophoneResult, type MicrophoneStreamOptions, type MotionAttitude, type MotionData, type MotionRotation, type MotionVector, type NormalizedAssetEntry, type NumberTweak, type OrientationData, type PlayablAssets, type PlayablAudio, type PlayablAudioAutoPauseOptions, type PlayablAudioContext, type PlayablAudioOptions, type PlayablDevice, type PlayablDevtools, PlayablError, type PlayablGame, type PlayablSDK, type PlayablTweaks, type ProgressionNoun, type ProgressionShape, type ReadyResult, type SaveResult, type SceneGrid, type SceneNode, type SceneRect, type SensorsAPI, type StateLevel, type SubmitResult, type TextTweak, type TweakAppliesOn, type TweakSchema, type TweakSchemaItem, type TweakType, type TweakValue, type TweakValueIssue, type TweakValueRejection, type TweakValues, type TweaksInitOptions, __testing, cellGridHooks, configure, sdk as default };
1096
+ export { type AssetDescriptor, type AssetEntry, type AssetKind, type AssetOverride, type AssetRecipe, type AssetStatus, type AssetType, type AssetValueEntry, type AssetsMapping, type AssetsRegisterOptions, type AssetsUrlMap, type AssetsValues, type BoardInstance, type BoardLayer, type BooleanTweak, type CameraAPI, type CameraOptions, type CameraResult, type CatalogCategory, type CatalogContext, type CatalogDefinition, type CatalogDefinitionOptions, type CatalogEntryAction, type CatalogEntryBase, type CatalogEntryOptions, type CatalogLevel, type CatalogLevelOptions, type CatalogProgression, type CatalogScreen, type CellGridEntry, type CellGridHooks, type CellGridOptions, type ColorTweak, type ContentDocument, type ContentFieldSpec, type ContentFieldType, type ContentFieldValue, type ContentGroup, type ContentHandle, type ContentHooks, type ContentLevel, type ContentOwner, type ContentRefusalCause, type ContentVerbType, type DevtoolsCommand, type DevtoolsContent, type DevtoolsHandle, type DevtoolsVocabulary, type EnumTweak, type ErrorCode, type FileSystemAPI, type FileSystemOptions, type FileSystemResult, type GameLoopHooks, type GameMode, type GameRunHandle, type GameRunOptions, type GeolocationAPI, type GeolocationOptions, type GeolocationResult, type HapticsAPI, type LayoutEntry, type LayoutFile, type LayoutRole, type LayoutRoleMap, type LayoutValues, type LevelPreview, type LevelPreviewCell, type LevelRefusal, type MicrophoneAPI, type MicrophoneRecordOptions, type MicrophoneResult, type MicrophoneStreamOptions, type MotionAttitude, type MotionData, type MotionRotation, type MotionVector, type NormalizedAssetEntry, type NumberTweak, type OrientationData, type PayloadRefusal, type PlayablAssets, type PlayablAudio, type PlayablAudioAutoPauseOptions, type PlayablAudioContext, type PlayablAudioOptions, type PlayablDevice, type PlayablDevtools, PlayablError, type PlayablGame, type PlayablSDK, type PlayablTweaks, type ProgressionNoun, type ProgressionShape, type ReadyResult, type SaveResult, type SceneGrid, type SceneNode, type SceneRect, type SensorsAPI, type StateLevel, type SubmitResult, type TextStyleStamp, type TextTweak, type TweakAppliesOn, type TweakSchema, type TweakSchemaItem, type TweakType, type TweakValue, type TweakValueIssue, type TweakValueRejection, type TweakValues, type TweaksInitOptions, __testing, cellGridHooks, configure, sdk as default };
package/dist/index.js CHANGED
@@ -3,13 +3,20 @@ var LOG_PREFIX = "[playabl/sdk]";
3
3
  var BASE_DOMAIN = "playabl.ai";
4
4
  var MANIFEST_PATH = "/Runtime-Script/sdk/v1/version.json";
5
5
  var ENV_HOST_RE = /\.(dev|staging)\.playabl\.ai$/;
6
- var FALLBACK_RUNTIME_URL = "https://cdn.playabl.ai/Runtime-Script/sdk/v1/runtime.js";
6
+ var CDN_HOSTS = /* @__PURE__ */ new Set([
7
+ "cdn.playabl.ai",
8
+ "cdn-staging.playabl.ai",
9
+ "cdn-dev.playabl.ai"
10
+ ]);
11
+ var FALLBACK_RUNTIME_URL = "https://cdn.playabl.ai/Runtime-Script/sdk/v1/runtime.js?v=sdk-1.1.0";
7
12
  function isEnv(value) {
8
13
  return value === "local" || value === "dev" || value === "staging" || value === "prod";
9
14
  }
10
- function detectEnv(hostname = typeof window !== "undefined" ? window.location.hostname : "", search = typeof window !== "undefined" ? window.location.search : "") {
15
+ function forcedEnv(search = typeof window !== "undefined" ? window.location.search : "") {
11
16
  const forced = new URLSearchParams(search).get("env");
12
- if (isEnv(forced)) return forced;
17
+ return isEnv(forced) ? forced : null;
18
+ }
19
+ function envFromHostname(hostname = typeof window !== "undefined" ? window.location.hostname : "") {
13
20
  if (hostname === "localhost" || hostname === "127.0.0.1") return "local";
14
21
  const match = hostname.match(ENV_HOST_RE);
15
22
  return match ? match[1] : "prod";
@@ -18,11 +25,52 @@ function manifestUrlForEnv(env) {
18
25
  const cdnHost = env === "prod" ? "cdn" : `cdn-${env}`;
19
26
  return `https://${cdnHost}.${BASE_DOMAIN}${MANIFEST_PATH}`;
20
27
  }
28
+ function isPlayablCdnUrl(value) {
29
+ let parsed;
30
+ try {
31
+ parsed = new URL(value);
32
+ } catch {
33
+ return false;
34
+ }
35
+ return parsed.protocol === "https:" && parsed.port === "" && CDN_HOSTS.has(parsed.hostname);
36
+ }
37
+ function describe(value) {
38
+ try {
39
+ return typeof value === "string" ? JSON.stringify(value) : `(${typeof value}) ${String(value)}`;
40
+ } catch {
41
+ return `(${typeof value}) (unprintable)`;
42
+ }
43
+ }
44
+ function injectedManifestUrl(source = typeof window !== "undefined" ? window : void 0) {
45
+ if (source === void 0) return void 0;
46
+ let value;
47
+ try {
48
+ value = source.__PLAYABL_MANIFEST_URL__;
49
+ } catch (error) {
50
+ console.warn(`${LOG_PREFIX} could not read window.__PLAYABL_MANIFEST_URL__; ignoring it`, error);
51
+ return void 0;
52
+ }
53
+ if (value === void 0) return void 0;
54
+ if (typeof value === "string" && isPlayablCdnUrl(value)) return value;
55
+ console.warn(
56
+ `${LOG_PREFIX} ignoring window.__PLAYABL_MANIFEST_URL__ ${describe(value)}: not an https URL on cdn.playabl.ai, cdn-staging.playabl.ai or cdn-dev.playabl.ai`
57
+ );
58
+ return void 0;
59
+ }
21
60
  async function resolveRuntimeUrl(options = {}) {
22
61
  if (options.runtimeUrl) return options.runtimeUrl;
23
- const env = detectEnv();
24
- if (!options.manifestUrl && env === "local") return FALLBACK_RUNTIME_URL;
25
- const manifestUrl = options.manifestUrl ?? manifestUrlForEnv(env);
62
+ let manifestUrl = options.manifestUrl;
63
+ if (!manifestUrl) {
64
+ const forced = forcedEnv();
65
+ const injected = forced === null ? injectedManifestUrl() : void 0;
66
+ if (injected) {
67
+ manifestUrl = injected;
68
+ } else {
69
+ const env = forced ?? envFromHostname();
70
+ if (env === "local") return FALLBACK_RUNTIME_URL;
71
+ manifestUrl = options.manifestUrl ?? manifestUrlForEnv(env);
72
+ }
73
+ }
26
74
  try {
27
75
  const response = await fetch(manifestUrl, { cache: "no-store" });
28
76
  if (!response.ok) throw new Error(`manifest HTTP ${response.status}`);
package/package.json CHANGED
@@ -1,12 +1,9 @@
1
1
  {
2
2
  "name": "@playabl/sdk",
3
- "version": "1.1.0-beta.0",
3
+ "version": "1.1.0",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
7
- "publishConfig": {
8
- "tag": "beta"
9
- },
10
7
  "files": [
11
8
  "dist/index.js",
12
9
  "dist/index.d.ts",