@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/dev/view/batch.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Turning one session projection into what each surface is owed.
+ *
+ * §12.3 and §12.6 say which messages a surface receives and which it blocks its
+ * first paint on. The old dev UI expressed that as four preview components with
+ * a copy of the batch each; here it is one pure function per surface kind,
+ * fed by the projection, and unit-testable without a browser.
+ *
+ * Projection is applied here, not in the surface: §7.4 requires a context to be
+ * narrowed to a surface's declared `reads` ∪ `writes` before it crosses the
+ * boundary, and a host that sends everything and lets the guest ignore the rest
+ * has not projected at all.
+ */
+import type { HostOverlay } from '@seriousgaming/sdk';
+import type { StateProjection } from '@seriousgaming/sdk/projection';
+import type { CrossTeamData, SessionData, TeamConfiguration, TeamLinks, WalkthroughLink } from '@seriousgaming/sdk/ui';
+import type { ViewerRole } from '../../core/protocol';
+import type { HostMessage } from '../../host';
+import type { MountableSurface } from '../surfaces';
+/** Who is looking, and at what. */
+export interface Viewer {
+    /** Stable index of the team whose surface this is, where there is one. */
+    teamIndex?: number;
+    /** The participant this render is identified as; absent for an observer. */
+    participantId?: string;
+    /** §13.3: an observer receives no `setParticipant`. */
+    observer?: boolean;
+    /**
+     * What the console holds this render as, where it holds it as anything
+     * (§13.3). Absent for a surface with no viewer behind it at all, such as
+     * the session console, the setup UI or the scenario editor.
+     *
+     * Not derivable from `participantId`, which is the point: the session has
+     * to be able to tell a participant the console could not name from a
+     * caller that legitimately names nobody (#566).
+     */
+    role?: ViewerRole;
+    /**
+     * The scenario a scenario editor is open on (§6.5), whose draft it edits.
+     * Absent for an editor opened on no scenario, and for every other surface.
+     */
+    scenario?: string;
+}
+export interface BatchOptions {
+    surface: MountableSurface;
+    state: StateProjection;
+    viewer: Viewer;
+    /**
+     * Resolved colour scheme, and the preference behind it. Omitted by the
+     * server, which cannot know a viewer's scheme: the page adds
+     * {@link themeMessages} of its own.
+     */
+    theme?: Theme;
+    /** Absolute origin of the console, which every link a surface is handed names. */
+    origin: string;
+    /** Absolute origin bundles and their assets are served from, where it differs. */
+    assetOrigin?: string;
+    /** The game's own name, which a session surface renders as the session's. */
+    gameName: string;
+    /** Whether the package ships a facilitator guide, which is one overlay. */
+    hasGuide?: boolean;
+    /** Whether a tick is running over this viewer's team (§12.4.4). */
+    roundProcessing?: boolean;
+    /**
+     * Show a presentation as if there were no session (§6.15): what it looks
+     * like in a game's library, or exported before the day.
+     */
+    sessionless?: boolean;
+    /** The active scenario's name in the session locale, for a presentation. */
+    scenarioName?: string | null;
+}
+/**
+ * Narrow a context to what a surface declared (§7.4).
+ *
+ * Anything undeclared is omitted rather than nulled: the guest's generated
+ * `Context` type does not have the property, so a surface reading one is a
+ * compile error rather than a runtime `null` it has to handle.
+ */
+export declare function projectContext(context: Record<string, Record<string, unknown>>, surface: MountableSurface): Record<string, Record<string, unknown>>;
+/**
+ * The settings a surface is sent: exactly the settings resources it declared
+ * (§8), resolved, on the same terms as capabilities (§7.4). For the setup UI
+ * and the scenario editor, the ones they edit.
+ */
+export declare function settingsFor(state: StateProjection, surface: MountableSurface, { withoutSession }?: {
+    withoutSession?: boolean;
+}): Record<string, Record<string, unknown>>;
+/**
+ * The settings the scenario editor is sent: its draft of the scenario it is
+ * open on (§6.5), never the session's. Nothing until that draft is open,
+ * since a frame seeded from the session's settings would show, and save, the
+ * wrong values.
+ */
+export declare function draftSettingsFor(state: StateProjection, surface: MountableSurface, viewer: Viewer): Record<string, Record<string, unknown>>;
+/**
+ * The `sessionKey` a surface is sent on `init` (§12.2).
+ *
+ * The run's own key, except for a surface shown outside any run: the scenario
+ * editor, which edits a scenario rather than a session (§6.5), and a
+ * presentation shown with no session (§6.15.1). Those get a key no run has,
+ * so nothing they store meets anything a session's surfaces store.
+ */
+export declare function sessionKeyFor(state: StateProjection, surface: Pick<MountableSurface, 'kind'>, { sessionless }?: {
+    sessionless?: boolean;
+}): string;
+/** A viewer's colour scheme, as the page resolved it. */
+export interface Theme {
+    mode: 'light' | 'dark';
+    preference: 'light' | 'dark' | 'system';
+    palette: unknown;
+}
+/** The two messages only the viewer's own page can compose. */
+export declare function themeMessages(theme: Theme): HostMessage[];
+/**
+ * The `setAssetUrls` payload (§12.3). Every prefix is absolute and ends in `/`.
+ *
+ * On the asset origin, beside the bundles, so a frame reads them as its own
+ * origin under `connect-src 'self'` and never needs the console's.
+ */
+export declare function assetUrls(assetOrigin: string): Record<string, string>;
+/**
+ * The whole initial batch for one surface.
+ *
+ * Ordered with the blocking messages first, so a guest that paints the moment
+ * its required set completes does so before the optional tail arrives.
+ */
+export declare function buildBatch(options: BatchOptions): HostMessage[];
+/**
+ * Every team's value of the capabilities a game UI reads across teams
+ * (§12.4.1), filtered here rather than in the frame: its own team's entry
+ * carries its whole declared set, every other team's only `crossTeamReads`.
+ */
+export declare function crossTeamData(state: StateProjection, surface: MountableSurface, ownTeamIndex: number | undefined): CrossTeamData;
+/**
+ * Where to open the walkthrough run (§5.7).
+ *
+ * A host route rather than a run, so it is the same before the run exists and
+ * after (§12.3), and the same from inside the walkthrough: a session has one,
+ * and that is where it opens.
+ */
+export declare function walkthroughLink(origin: string): WalkthroughLink;
+/**
+ * The host-owned overlays a session surface may open (§6.4).
+ *
+ * Both of these are the console's own pages rather than anything the game
+ * mounts, which is what makes them the host's to offer: a facilitator on a
+ * surface that owns the whole canvas can reach the guide and the team sheets
+ * without leaving it. A guide is offered only when the package ships one — a
+ * control for an overlay the host does not have is a control that cannot work.
+ */
+export declare function availableOverlays(hasGuide?: boolean): HostOverlay[];
+/**
+ * One join and observe URL per team, for the facilitator surface.
+ *
+ * The join URL is a route that resolves: it asks which participant you are, or
+ * opens straight into the surface when the team holds one. There is no PIN and
+ * no account here, so a link is the whole of joining — which is also why there
+ * is no `fallbackJoinUrl`: one origin, one form of the link.
+ */
+export declare function teamLinks(state: StateProjection, origin: string): TeamLinks[];
+/** The mode and the **effective** bounds a surface gates its controls on (§5.4). */
+export declare function teamConfiguration(state: StateProjection): TeamConfiguration;
+/**
+ * `SessionData`: the shared store once, and every team's own state **keyed by
+ * teamId**.
+ *
+ * A map, not an array. The wrapper indexes it by id, so an array renders as a
+ * session with no teams in it. A team's context omits the shared capabilities,
+ * which the projection composes into every team's view: they are in `shared`,
+ * once, rather than repeated per team.
+ */
+export declare function sessionData(state: StateProjection, surface: MountableSurface): SessionData;

package/dist/dev/view/commands.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Turning what a surface asks for into a session command, on the viewer's
+ * behalf rather than on the surface's word.
+ *
+ * Shared by the operator console, which runs it in the browser, and by the
+ * server's per-viewer feed, which runs it on a page's raw frame messages so
+ * that who is asking is decided by the host and never by the page (§13.2).
+ */
+import type { Command, QueryCommand, ViewerRole } from '../../core/protocol';
+import type { MountableSurface } from '../surfaces';
+import type { Viewer } from './batch';
+/** The team a command addresses, where the viewer is on one. */
+export declare function teamScope(viewer: Viewer): {
+    teamIndex?: number;
+};
+/** Who is asking, where the viewer resolved to somebody. */
+export declare function actorOf(viewer: Viewer): {
+    participantId?: string;
+    teamId?: string;
+};
+/**
+ * What the console holds this render as (§13.3).
+ *
+ * Kept apart from {@link actorOf} rather than folded into it, for two reasons:
+ * `renameOwnTeam` takes the actor and has no viewer role to take, and the
+ * session needs the role most precisely when the actor is empty, which is the
+ * case it could not otherwise tell from a legitimately anonymous write (#566).
+ */
+export declare function roleOf(viewer: Viewer): {
+    viewerRole?: ViewerRole;
+};
+/** Everything a command carries about who sent it. */
+export declare function viewerFields(viewer: Viewer): {
+    teamIndex?: number;
+    participantId?: string;
+    teamId?: string;
+    viewerRole?: ViewerRole;
+};
+/**
+ * A message this surface may send, carrying something the host must decide
+ * for itself: a `teamId` on a session-wide or self-addressed command (§12.5).
+ * Refused rather than stripped, so the surface learns it named something it
+ * may not.
+ */
+export interface FrameRefusal {
+    refused: string;
+}
+export declare function isFrameRefusal(value: unknown): value is FrameRefusal;
+/**
+ * Turn a guest message the channel does not own into a session command.
+ *
+ * The channel answers requests (endpoints, blobs, history); what reaches here
+ * is everything a surface asks the *session* to do, which is one mapping table
+ * rather than the switch-of-switches the old host grew.
+ *
+ * Returns `null` for a message this host does not act on, or one this kind of
+ * surface may not send, so the caller can tell 'nothing to do' from 'done'.
+ */
+export declare function commandFor(message: {
+    type: string;
+    [key: string]: unknown;
+}, surface: MountableSurface, viewer: Viewer): Command | FrameRefusal | null;
+/**
+ * Turn a guest read into a session query, carrying the viewer's identity and
+ * the surface's own identifier, never the page's.
+ *
+ * `uiIdentifier` is what bounds the answer: the session projects a surface's
+ * history onto what it declared and gates the cross-team roster on
+ * `crossTeamParticipants` (§12.5), so a caller that could name another surface
+ * could read what that surface may.
+ */
+export declare function queryFor(message: {
+    type: string;
+    [key: string]: unknown;
+}, surface: MountableSurface, viewer: Viewer): QueryCommand | null;

package/dist/dev/view/route.d.ts

@@ -0,0 +1,58 @@
+import type { RunKind } from '@seriousgaming/sdk';
+/**
+ * Which surface a URL names.
+ *
+ * Every surface is directly addressable and guessable. The old dev UI resolved
+ * a default participant server-side and redirected `/play/2` to
+ * `/play/2/participant/<id>`; here the URL says what it means and nothing
+ * redirects, so an agent can open `/team/2/player/1` without asking what the
+ * link is.
+ *
+ * `?bare` drops the dev chrome entirely, which is what you screenshot, what you
+ * hand somebody, and what a browser test drives: a visual change to the chrome
+ * then cannot fail a game test.
+ *
+ * `/team/2/join` is the one route that resolves rather than names: it is what a
+ * facilitator hands out, and it asks which participant you are — or, when the
+ * team holds one, simply opens as them.
+ *
+ * `/walkthrough` names the walkthrough run's play surface (§5.7). It takes no
+ * team or participant because a walkthrough holds one of each, so there is
+ * nothing to choose: it is the view you put on the projector while you talk the
+ * room through the game.
+ *
+ * `/presentation` is the facilitator's deck (§6.15), and `?preview` shows it as
+ * it looks with no session: in a library, or exported before the day.
+ */
+export type RouteKind = 'console' | 'player' | 'observer' | 'join' | 'waiting-room' | 'setup' | 'scenario-editor' | 'guide' | 'print' | 'presentation';
+export interface Route {
+    kind: RouteKind;
+    /**
+     * Which run the surface belongs to (§5.7). The session unless the URL says
+     * `/walkthrough`, which is what every existing link means.
+     */
+    run: RunKind;
+    /** Stable team index, where the route names a team. */
+    teamIndex?: number;
+    /** Participant position within the team, 1-based in the URL. */
+    participant?: number;
+    /**
+     * Which scenario the scenario editor is editing.
+     *
+     * The editor has no standalone entry: it is always opened *on* a scenario,
+     * from the dev drawer's Scenario tab. Without one there is nothing for it
+     * to save into, and an editor that cannot save is a screen that wastes the
+     * work somebody does on it.
+     */
+    scenario?: string;
+    /** No dev chrome: exactly what a participant sees. */
+    bare: boolean;
+    /** Show a presentation as if there were no session (§6.15). */
+    preview?: boolean;
+}
+export declare function parseRoute(pathname: string, search: string): Route;
+/** The URL for a route, so the console links rather than constructs by hand. */
+export declare function routeHref(route: Omit<Route, 'bare' | 'run'> & {
+    bare?: boolean;
+    run?: RunKind;
+}): string;

package/dist/dev/view/view.d.ts

@@ -0,0 +1,78 @@
+/**
+ * What one viewer's page shows, decided by the host.
+ *
+ * A `?bare` page is somebody's device: a participant who followed a join link,
+ * an observer, a facilitator's session surface on a projector. §7.4 requires a
+ * runtime serving such a device to project before the payload leaves it, so
+ * everything the page needs is resolved here, on the server, and the page is
+ * sent only the answer: which surface to mount, and the messages it is owed.
+ * The operator console, which renders its own inspector in the same document
+ * as the frame, keeps the whole projection and resolves the same rules itself.
+ */
+import type { StateProjection } from '@seriousgaming/sdk/projection';
+import type { HostMessage, SurfaceKind } from '../../host';
+import type { MountableSurface } from '../surfaces';
+import { type Viewer } from './batch';
+import { type Route, type RouteKind } from './route';
+/** Which bundle a route mounts. */
+export declare const SURFACE_FOR: Partial<Record<RouteKind, SurfaceKind>>;
+/** Whether a route is served as a viewer page, with a server-built feed. */
+export declare function isViewRoute(route: Route): boolean;
+/** A team as its join page shows it: its name and who is on it, nothing else. */
+export interface JoinTeam {
+    index: number;
+    name: string;
+    participants: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export type ViewPage = {
+    status: 'surface';
+    surface: MountableSurface;
+    viewer: Viewer;
+    inSetup: boolean;
+    /** What the frame is sent on `init` (§12.2). */
+    sessionKey: string;
+}
+/** A participant's page while the facilitator is still configuring. */
+ | {
+    status: 'configuring';
+}
+/** The setup surface, after the session has started. */
+ | {
+    status: 'closed';
+    configurable: boolean;
+} | {
+    status: 'join';
+    team: JoinTeam | null;
+} | {
+    status: 'redirect';
+    href: string;
+} | {
+    status: 'no-such-team';
+    teamIndex: number;
+} | {
+    status: 'no-such-participant';
+    teamIndex: number;
+    slot: number;
+    held: number;
+} | {
+    status: 'missing-surface';
+    kind: SurfaceKind;
+};
+/**
+ * Resolve a viewer page, by the rules the operator console applies: the
+ * configuration step first (§8.3), the waiting-room hold (§6.14.1), and a
+ * refusal for a URL that names somebody who is not there (§13.2).
+ */
+export declare function resolveView(state: StateProjection, route: Route, surfaces: MountableSurface[]): ViewPage;
+export interface ViewMessageOptions {
+    origin: string;
+    assetOrigin: string;
+    gameName: string;
+    hasGuide: boolean;
+    roundProcessing: boolean;
+}
+/** Every message a viewer page's surface is owed, less the theme the page adds. */
+export declare function viewMessages(page: ViewPage, state: StateProjection, options: ViewMessageOptions): HostMessage[];

package/dist/dev/view/viewer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Who a route says is looking, resolved against the roster.
+ *
+ * Addressing identity in the URL (§13.2) means a URL can name somebody who is
+ * not there. `/team/1/player/3` on a team holding two used to resolve to no
+ * participant and mount anyway: the surface rendered, and because its writes
+ * then named nobody, the session took them as system-trusted and applied them
+ * unvalidated (#566).
+ *
+ * So resolution has three outcomes, not two. A slot the roster does not hold
+ * is its own answer, and the console refuses the surface rather than mounting
+ * an identity-free one. `role` carries the other half: it says what the
+ * console holds a render as, independently of whether it managed to name
+ * anybody, which is what lets the session tell a participant it cannot
+ * attribute from a caller that legitimately has no identity (§13.3).
+ */
+import type { StateProjection } from '@seriousgaming/sdk/projection';
+import type { Viewer } from './batch';
+import type { Route } from './route';
+export type ViewerResolution = {
+    kind: 'viewer';
+    viewer: Viewer;
+} | {
+    kind: 'no-such-team';
+    teamIndex: number;
+} | {
+    kind: 'no-such-participant';
+    teamIndex: number;
+    slot: number;
+    held: number;
+};
+export declare function resolveViewer(state: StateProjection, route: Route): ViewerResolution;

package/dist/discovery/config.d.ts

@@ -0,0 +1,9 @@
+import { ResolvedPackageManifest } from '@seriousgaming/sdk';
+/**
+ * Load a package and everything it declares.
+ *
+ * A package's resources are its own, and it declares them by having them: each
+ * kind is read from its conventional directory beside the manifest (#431).
+ * There is no cross-package resource reuse and no list to fall out of step.
+ */
+export declare function loadConfig(configPath: string): Promise<ResolvedPackageManifest>;

package/dist/discovery/manifest-paths.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Rewrite Windows separators to forward slashes.
+ *
+ * A resource identifier is reverse-DNS and a resource directory name is
+ * machine-composed from it, so neither can legitimately contain a backslash
+ * and there is nothing here to preserve on a POSIX host.
+ */
+export declare function toPosixPath(value: string): string;
+/**
+ * Compose the `rootDirectory` a resource carries into the runtime manifest,
+ * from the path its bundle file was found at and the `rootDirectory` the bundle
+ * declares.
+ *
+ * A manifest `rootDirectory` is a POSIX-relative path: the platform joins it
+ * with forward slashes to address the resource over HTTP, and the resulting
+ * address maps 1-1 onto an object-storage key. `path.join` would normalise to
+ * the host separator instead, which put a backslash into every manifest built
+ * on Windows (#503), so the composition is done in POSIX terms on every
+ * platform and never through the ambient `path`.
+ */
+export declare function resolveManifestRootDirectory(resourcePath: string, declaredRootDirectory: string): string;

package/dist/discovery/removed-fields.d.ts

@@ -0,0 +1,90 @@
+/**
+ * What a package no longer authors, and what to do instead.
+ *
+ * Every schema object is closed, so anything here would fail schema validation
+ * anyway, as an unknown property that says nothing about what replaced it. The
+ * loader checks this table first, so an author upgrading a package hears where
+ * each field went. Anything not listed gets the schema's own error, whose hint
+ * points at the upgrading guide.
+ *
+ * The constants are shared with the guard on `new` and `update` input, so the
+ * two say the same thing.
+ */
+import { type ResourceType } from '../templating/resource-metadata.js';
+/** The refusal for an authored `configurationSchema` on any bundle (#597). */
+export declare const REMOVED_CONFIGURATION_SCHEMA: string;
+/** The refusal for the game-level `configuration` block (#597). */
+export declare const REMOVED_GAME_CONFIGURATION: string;
+/** The refusal for a scenario still carrying `configuration` (#634). */
+export declare const RENAMED_SCENARIO_CONFIGURATION: string;
+/**
+ * The refusal for `uses` on a user interface (#635). A UI reaches a service
+ * only through an endpoint, so the field was refused or ignored for every
+ * value it could hold.
+ */
+export declare const REMOVED_UI_USES: string;
+/** The refusal for demo mode's `demo` block, on the manifest or a scenario (#635). */
+export declare const REMOVED_DEMO: string;
+/**
+ * The refusal for the manifest's `configurationSurfaces` map (#637). The two
+ * surfaces it wired are slots of their own now, so a bundle is wired by where
+ * it sits rather than by a name in the manifest.
+ */
+export declare const REMOVED_CONFIGURATION_SURFACES: string;
+/** The refusal for the manifest's `ticks`, renamed so it has one name everywhere (#671). */
+export declare const RENAMED_MANIFEST_TICKS: string;
+/**
+ * The refusal for a scenario's game-level fields (#671). They are the built-in
+ * `game` settings now, which a scenario overrides under `settings.game` like
+ * any other settings resource.
+ */
+export declare function movedScenarioGameField(key: 'ticks' | 'teams' | 'waitingRoom', value: unknown): string;
+/** The hint on a schema error the table does not explain. */
+export declare const UPGRADING_HINT = "If this package was written for an earlier SDK, `seriousgaming-sdk docs view guides/upgrading.md` says what changed.";
+/**
+ * Where a removed thing sat: the manifest, a directory beside it (`package`),
+ * every resource bundle, or the bundles of the types listed.
+ */
+export type RemovedSite = 'manifest' | 'package' | 'every bundle' | readonly ResourceType[];
+export interface RemovedField {
+    where: RemovedSite;
+    /**
+     * The path to it inside the file, `*` standing for each entry of an array.
+     * For a `package` row, the directory's name.
+     */
+    path: readonly string[];
+    /** The release that removed it. */
+    since: string;
+    /**
+     * What is wrong, then what to do. Without a `hint`, the first sentence is
+     * the diagnostic's message and the rest its hint.
+     */
+    message: string | ((value: unknown) => string);
+    /** The hint, where it is not the message's own second half. */
+    hint?: string;
+    /** Refuse only a value this accepts; by default, any value at all. */
+    when?: (value: unknown) => boolean;
+}
+/** One refusal found, with where it was found. */
+export interface RemovedFieldMatch {
+    field: RemovedField;
+    /** The path to the value, array positions resolved. */
+    pointer: Array<string | number>;
+    /** The whole explanation: what is wrong, then what to do. */
+    explanation: string;
+    /** The same, split for a diagnostic. */
+    message: string;
+    hint?: string;
+}
+/**
+ * Everything a package no longer authors, in the order it is reported: the
+ * manifest and the layout first, then each bundle.
+ */
+export declare const REMOVED_FIELDS: readonly RemovedField[];
+/**
+ * What the manifest and the layout beside it still carry, in table order.
+ * `directoryExists` answers for a directory named relative to the package.
+ */
+export declare function removedFromPackage(manifest: unknown, directoryExists: (directory: string) => boolean): RemovedFieldMatch[];
+/** What one bundle of `type` still carries, in table order. */
+export declare function removedFromBundle(type: ResourceType, bundle: unknown): RemovedFieldMatch[];