@memizy/host-sdk 1.0.0-rc.6 → 1.0.0-rc.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog of @memizy/host-sdk
 
+## 1.0.0-rc.7 (2026-10-16)
+
+* `LocalSession` gives the authority a secret random seed (`InitPayload.seed`; `SessionConfig.seed` only for replays and tests).
+* The default seed of the display order (`shuffleSeed`) is random, no longer the session id: a player knows the session id and could undo the shuffle (authors often write sets in the answer's order). Pass the same `shuffleSeed` to continue a saved game.
+* `getAsset` gives a player's instance in multiplayer only media of its own (public) set: media of the back of a flashcard or of an explanation can no longer be fetched by key.
+* `recordAnswer` is accepted only from the authority (SPEC 5): another instance cannot prove an answer, so a modified player's device cannot write "correct" into a teacher's statistics.
+* Answers to `open-ended` items are kept, not graded: the `answer` event has `ungraded: true` and no record, the learning progress is unchanged. Every `answer` event carries `setId` (an item is identified by set + item ID).
+* `prepareSetForPlugin` leaves out items whose `mustUnderstand` names properties this version does not support.
+* `leitner` keeps the learner's `starred` and fields of a later OQSEP version (also in `stats`) and stores the answer as `lastAnswer.answer`; the `LearningAlgorithm` contract says so.
+* `LocalSession` gives settings of a later protocol version their default and ignores values sent for them.
+* Public items of a session come from the new fail-closed `publicItem` of `@memizy/protocol`.
+
 ## 1.0.0-rc.6 (2026-10-14)
 
 Enforces the final protocol 1.0 ([SPEC](https://github.com/memizy/memizy/blob/main/packages/protocol/SPEC.md)).

package/README.md

@@ -61,6 +61,6 @@ const player = new RelayPlayer({ serverUrl: 'https://mp.memizy.com', pin, name:
 
 `uploadBundle` takes the `PreparedSet` and uploads only its `publicSet`: anyone with the PIN can download the bundle, so answers never leave the host. Use the same seed for the bundle and `shuffleSeed`, so every device shows the same order.
 
-**Continuing a saved game** (SPEC 3.3): create the session with the saved players (their old IDs), the same `sessionId`, `shuffleSeed` and storage, `restore: true` and a paused `clock`, then `host.attach(session, { seats: true })`. Devices see the earlier places in `state.seats` and take one with `player.claimSeat(id)` (or `claimSeat(null)` to join as a new player when the game allows late joins); the host can change it with `host.assignSeat(roomPlayerId, seatId)` (`host.seats` lists the places with their `roomPlayerId`). Keep `host.seatAssignments` and pass it as `taken` to attach again after a reload of the host page. Memizy Play (`apps/play`, `HostView` and `JoinView`) is the reference host.
+**Continuing a saved game** (SPEC 3.3): create the session with the saved players (their old IDs), the same `sessionId`, `shuffleSeed` and storage, `restore: true` and a paused `clock`, then `host.attach(session, { seats: true })`. Devices see the earlier places in `state.seats` and take one with `player.claimSeat(id)` (or `claimSeat(null)` to join as a new player when the game allows late joins); the host can change it with `host.assignSeat(roomPlayerId, seatId)` (`host.seats` lists the places with their `roomPlayerId`). Keep `host.seatAssignments` and pass it as `taken` to attach again after a reload of the host page. Memizy Play ([memizy.com/play](https://memizy.com/play/)) uses exactly this flow.
 
 Iframes are sandboxed with `allow-scripts allow-forms allow-modals allow-pointer-lock allow-popups allow-popups-to-escape-sandbox` (`PLUGIN_SANDBOX`; links open in a new tab) and **never** `allow-same-origin` or `allow-top-navigation`.

package/dist/learning.cjs

@@ -1 +1 @@
-var e=[0,1,3,7,21],t={id:`leitner`,apply(t,n,r){let i=t?.stats??{attempts:0,incorrect:0,streak:0},a={isCorrect:!n.isSkipped&&n.isCorrect,answeredAt:r.toISOString(),...n.confidence!==void 0&&{confidence:n.confidence},...n.timeSpentMs!==void 0&&{timeSpent:n.timeSpentMs},...n.hintsUsed!==void 0&&{hintsUsed:n.hintsUsed},...n.isSkipped&&{isSkipped:!0}};if(n.isSkipped)return{...t??{bucket:0},stats:i,lastAnswer:a};let o=n.isCorrect?Math.min(4,Math.max(1,t?.bucket??0)+1):1,s=new Date(r.getTime()+e[o]*24*60*60*1e3);return{...t,bucket:o,nextReviewAt:s.toISOString(),stats:{attempts:i.attempts+1,incorrect:i.incorrect+ +!n.isCorrect,streak:n.isCorrect?i.streak+1:0},lastAnswer:a}}};exports.LEITNER_INTERVAL_DAYS=e,exports.leitner=t;
+var e=[0,1,3,7,21],t={id:`leitner`,apply(t,n,r){let i=t?.stats??{attempts:0,incorrect:0,streak:0},a={isCorrect:!n.isSkipped&&n.isCorrect,answeredAt:r.toISOString(),...n.confidence!==void 0&&{confidence:n.confidence},...n.timeSpentMs!==void 0&&{timeSpent:n.timeSpentMs},...n.hintsUsed!==void 0&&{hintsUsed:n.hintsUsed},...n.isSkipped&&{isSkipped:!0},...n.answer!==void 0&&{answer:n.answer}};if(n.isSkipped)return{...t??{bucket:0},stats:i,lastAnswer:a};let o=n.isCorrect?Math.min(4,Math.max(1,t?.bucket??0)+1):1,s=new Date(r.getTime()+e[o]*24*60*60*1e3);return{...t,bucket:o,nextReviewAt:s.toISOString(),stats:{...i,attempts:i.attempts+1,incorrect:i.incorrect+ +!n.isCorrect,streak:n.isCorrect?i.streak+1:0},lastAnswer:a}}};exports.LEITNER_INTERVAL_DAYS=e,exports.leitner=t;

package/dist/learning.js

@@ -18,7 +18,8 @@ var e = [
 			...n.confidence !== void 0 && { confidence: n.confidence },
 			...n.timeSpentMs !== void 0 && { timeSpent: n.timeSpentMs },
 			...n.hintsUsed !== void 0 && { hintsUsed: n.hintsUsed },
-			...n.isSkipped && { isSkipped: !0 }
+			...n.isSkipped && { isSkipped: !0 },
+			...n.answer !== void 0 && { answer: n.answer }
 		};
 		if (n.isSkipped) return {
 			...t ?? { bucket: 0 },
@@ -31,6 +32,7 @@ var e = [
 			bucket: o,
 			nextReviewAt: s.toISOString(),
 			stats: {
+				...i,
 				attempts: i.attempts + 1,
 				incorrect: i.incorrect + +!n.isCorrect,
 				streak: n.isCorrect ? i.streak + 1 : 0

package/dist/plugin.cjs

@@ -1 +1 @@
-let e=require("@memizy/protocol"),t=require("@memizy/oqse");function n(t){let n=(0,e.readPluginManifestFromHtml)(t);return n.success?(0,e.isProtocolSupported)(n.runtime.protocol)?{success:!0,plugin:{html:t,manifest:n.manifest,runtime:n.runtime}}:{success:!1,errors:[`The plugin needs Memizy Plugin Protocol ${n.runtime.protocol}, which this host does not support.`]}:n}async function r(e,t=fetch){let r=await t(e);return r.ok?n(await r.text()):{success:!1,errors:[`Could not download the plugin (${r.status} ${r.statusText}).`]}}function i(n,r,i={}){let a=r.capabilities?.types??[],o=a.includes(`*`)?n.items:n.items.filter(e=>a.includes(e.type)),s=(0,e.prepareDisplaySet)({meta:n.meta,items:o},i.seed);return{set:s.set,publicSet:s.publicSet,compatibility:(0,t.checkCompatibility)(n,r),skippedItems:n.items.length-o.length}}function a(e){let n=new Date().toISOString();return{version:t.OQSE_VERSION,meta:{id:(0,t.generateUUID)(),title:e.title,language:e.language,createdAt:n,updatedAt:n},items:[]}}exports.createEmptySet=a,exports.loadPluginFromHtml=n,exports.loadPluginFromUrl=r,exports.prepareSetForPlugin=i;
+let e=require("@memizy/protocol"),t=require("@memizy/oqse");function n(t){let n=(0,e.readPluginManifestFromHtml)(t);return n.success?(0,e.isProtocolSupported)(n.runtime.protocol)?{success:!0,plugin:{html:t,manifest:n.manifest,runtime:n.runtime}}:{success:!1,errors:[`The plugin needs Memizy Plugin Protocol ${n.runtime.protocol}, which this host does not support.`]}:n}async function r(e,t=fetch){let r=await t(e);return r.ok?n(await r.text()):{success:!1,errors:[`Could not download the plugin (${r.status} ${r.statusText}).`]}}function i(n,r,i={}){let a=r.capabilities?.types??[],o=(a.includes(`*`)?n.items:n.items.filter(e=>a.includes(e.type))).filter(e=>(0,t.missingMustUnderstand)(e).length===0),s=(0,e.prepareDisplaySet)({meta:n.meta,items:o},i.seed);return{set:s.set,publicSet:s.publicSet,compatibility:(0,t.checkCompatibility)(n,r),skippedItems:n.items.length-o.length}}function a(e){let n=new Date().toISOString();return{version:t.OQSE_VERSION,meta:{id:(0,t.generateUUID)(),title:e.title,language:e.language,createdAt:n,updatedAt:n},items:[]}}exports.createEmptySet=a,exports.loadPluginFromHtml=n,exports.loadPluginFromUrl=r,exports.prepareSetForPlugin=i;

package/dist/plugin.js

@@ -1,7 +1,7 @@
 import { isProtocolSupported as e, prepareDisplaySet as t, readPluginManifestFromHtml as n } from "@memizy/protocol";
-import { OQSE_VERSION as r, checkCompatibility as i, generateUUID as a } from "@memizy/oqse";
+import { OQSE_VERSION as r, checkCompatibility as i, generateUUID as a, missingMustUnderstand as o } from "@memizy/oqse";
 //#region src/plugin.ts
-function o(t) {
+function s(t) {
 	let r = n(t);
 	return r.success ? e(r.runtime.protocol) ? {
 		success: !0,
@@ -15,26 +15,26 @@ function o(t) {
 		errors: [`The plugin needs Memizy Plugin Protocol ${r.runtime.protocol}, which this host does not support.`]
 	} : r;
 }
-async function s(e, t = fetch) {
+async function c(e, t = fetch) {
 	let n = await t(e);
-	return n.ok ? o(await n.text()) : {
+	return n.ok ? s(await n.text()) : {
 		success: !1,
 		errors: [`Could not download the plugin (${n.status} ${n.statusText}).`]
 	};
 }
-function c(e, n, r = {}) {
-	let a = n.capabilities?.types ?? [], o = a.includes("*") ? e.items : e.items.filter((e) => a.includes(e.type)), s = t({
+function l(e, n, r = {}) {
+	let a = n.capabilities?.types ?? [], s = (a.includes("*") ? e.items : e.items.filter((e) => a.includes(e.type))).filter((e) => o(e).length === 0), c = t({
 		meta: e.meta,
-		items: o
+		items: s
 	}, r.seed);
 	return {
-		set: s.set,
-		publicSet: s.publicSet,
+		set: c.set,
+		publicSet: c.publicSet,
 		compatibility: i(e, n),
-		skippedItems: e.items.length - o.length
+		skippedItems: e.items.length - s.length
 	};
 }
-function l(e) {
+function u(e) {
 	let t = (/* @__PURE__ */ new Date()).toISOString();
 	return {
 		version: r,
@@ -49,4 +49,4 @@ function l(e) {
 	};
 }
 //#endregion
-export { l as createEmptySet, o as loadPluginFromHtml, s as loadPluginFromUrl, c as prepareSetForPlugin };
+export { u as createEmptySet, s as loadPluginFromHtml, c as loadPluginFromUrl, l as prepareSetForPlugin };

package/dist/session.cjs

@@ -1 +1 @@
-require("./version.cjs");const e=require("./plugin.cjs"),t=require("./learning.cjs"),n=require("./storage.cjs");let r=require("@memizy/protocol"),i=require("@memizy/oqse"),a=require("@memizy/protocol/internal");function o(e){try{return structuredClone(e)}catch{return JSON.parse(JSON.stringify(e))}}var s=class{id;plugin;runtime;mode;hostAs;authority;prepared;roster;settingValues;settingsOk=!0;hostConfig;isStarted=!1;isEnded=!1;pauseState={pausedMs:0,pausedAt:null};options;storage;algorithm;instances=new Map;listeners=new Set;authorityConnected=!0;startPromise=null;resumeStartPending=!1;pendingSnapshot=void 0;finished=!1;hasResult=!1;finishedSnapshot=null;snapshotTimer;pendingData=new Map;get players(){return this.roster}get settings(){return this.settingValues}get settingsValid(){return this.settingsOk}get config(){return this.hostConfig}get started(){return this.isStarted}get ended(){return this.isEnded}constructor(i){if(this.options=i,this.id=i.sessionId??`session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2,8)}`,this.plugin=i.plugin,this.runtime=i.plugin.runtime,this.mode=i.mode,this.storage=i.storage??new n.MemoryStorage,this.algorithm=i.algorithm??t.leitner,this.hostConfig={locale:i.locale??`en`,theme:i.theme??`light`},i.mode===`solo`){if(!this.runtime.solo)throw Error(`The plugin does not support solo mode.`);this.hostAs=null}else{if(!this.runtime.multiplayer)throw Error(`The plugin does not support multiplayer.`);let e=i.hostAs??this.runtime.multiplayer.hostAs[0];if(!this.runtime.multiplayer.hostAs.includes(e))throw Error(`The plugin does not support hostAs "${e}".`);this.hostAs=e}let a=i.players??(i.mode===`solo`?[{id:`player`,name:`Player`,isHost:!0}]:[]);if(i.mode===`solo`&&a.length!==1)throw Error(`A solo session has exactly one player.`);if(new Set(a.map(e=>e.id)).size!==a.length)throw Error(`Player IDs must be unique.`);if(a.some(e=>e.id===r.BOARD_ADDRESS||e.id===r.SETTINGS_ADDRESS||e.id===`server`))throw Error(`Player IDs "board", "settings" and "server" are reserved.`);if(this.roster=a.map(e=>({id:e.id,name:e.name,isHost:i.mode===`solo`?!0:e.isHost??!1,connected:!0})),i.mode===`solo`)this.authority=this.roster[0].id;else if(this.hostAs===`presenter`)this.authority=r.BOARD_ADDRESS;else{let e=this.roster.find(e=>e.isHost);if(!e)throw Error(`With hostAs "player", one player must have isHost: true.`);this.authority=e.id}let s=(0,r.resolveSettings)(this.runtime.settings,i.settings??{});if(s.errors.length>0)throw Error(`Invalid settings: ${s.errors.join(`; `)}`);this.settingValues=s.values;let c=i.shuffleSeed===null?void 0:i.shuffleSeed??this.id;this.prepared=e.prepareSetForPlugin(o(i.set),i.plugin.manifest,{seed:c}),i.restore&&(this.isStarted=!0,this.resumeStartPending=!0),i.clock&&(this.pauseState={pausedMs:i.clock.pausedMs??0,pausedAt:i.clock.pausedAt??null})}on(e){return this.listeners.add(e),()=>this.listeners.delete(e)}emit(e){for(let t of this.listeners)try{t(e)}catch(e){console.error(`[memizy host] session listener failed:`,e)}}viewOf(e){return e===r.SETTINGS_ADDRESS?`settings`:this.mode===`solo`?`solo`:e===r.BOARD_ADDRESS?`board`:`controller`}addresses(){return[...this.hostAs===`presenter`?[r.BOARD_ADDRESS]:[],...this.roster.map(e=>e.id)]}async connect(e,t,n={}){let i=this.viewOf(e);if(i===`settings`){if(!this.runtime.multiplayer||!this.runtime.settingsScreen)throw Error(`The plugin has no settings screen (settingsScreen).`);if(this.isStarted)throw Error(`The settings screen is only available before the game starts.`)}else if(!this.addresses().includes(e))throw Error(`Unknown address "${e}" in this session.`);if(this.isEnded)throw Error(`The session has ended.`);this.disposeInstance(e);let o={address:e,view:i,hostApi:void 0,endpoint:t,onDispose:n.onDispose,plugin:null,ready:!1,connected:!0,disposed:!1,resumed:!1,greeted:!1,limiter:new a.RateLimiter(r.LIMITS.messagesPerSecond,r.LIMITS.messageBurst),serviceLimiter:new a.RateLimiter(r.LIMITS.servicesPerMinute/60,10),answerLimiter:new a.RateLimiter(r.LIMITS.answersPerSecond,r.LIMITS.answerBurst),assetLimiter:new a.RateLimiter(r.LIMITS.assetsPerSecond,r.LIMITS.assetBurst),errorLimiter:new a.RateLimiter(r.LIMITS.errorReportsPerSecond,r.LIMITS.errorReportBurst)};o.hostApi=this.createHostApi(o),this.instances.set(e,o),e===this.authority&&this.isStarted&&this.setAuthorityConnected(!1);try{o.plugin=await t(o.hostApi)}catch(e){if(o.disposed)return o;throw e}return o}async reload(e){let t=this.instances.get(e);if(!t)throw Error(`No instance at "${e}".`);return e===this.authority&&await this.flushSnapshot(),this.connect(e,t.endpoint,{onDispose:t.onDispose})}disconnect(e){this.disposeInstance(e),e===this.authority&&this.isStarted&&this.setAuthorityConnected(!1)}disposeInstance(e){let t=this.instances.get(e);if(t){t.disposed=!0,this.instances.delete(e);try{t.onDispose?.()}catch(e){console.warn(`[memizy host] dispose failed:`,e)}}}getInstance(e){return this.instances.get(e)}start(){if(this.mode===`solo`||this.isStarted&&!this.startPromise)return Promise.resolve();if(!this.settingsOk)return Promise.reject(Error(`The settings are not valid.`));let e=this.roster.length,t=this.runtime.multiplayer.players;return e<t.min||e>t.max?Promise.reject(Error(`This plugin needs ${t.min}–${t.max} players (now ${e}).`)):(this.startPromise??=this.runStart(),this.startPromise)}async runStart(){this.disposeInstance(r.SETTINGS_ADDRESS);let e=Date.now()+(this.options.readyTimeoutMs??15e3),t=()=>[...this.instances.values()].every(e=>e.ready),n=()=>this.instances.get(this.authority)?.ready===!0;for(;!(t()&&n())&&(Date.now()<e||!n());){if(this.isEnded)return;await c(25)}let i=this.options.countdownMs??3e3;for(let e=Math.ceil(i/1e3);e>0;e--)this.emit({type:`countdown`,secondsLeft:e}),await c(Math.min(1e3,i-(Math.ceil(i/1e3)-e)*1e3));this.isEnded||(this.isStarted=!0,this.emit({type:`started`}),await this.callPlugin(this.authority,e=>e.start()))}addPlayer(e){if(this.mode===`solo`)throw Error(`Players cannot join a solo session.`);if(this.roster.some(t=>t.id===e.id)||[r.BOARD_ADDRESS,r.SETTINGS_ADDRESS,`server`].includes(e.id))throw Error(`Player ID "${e.id}" is already used or reserved.`);if(this.isStarted&&!this.runtime.multiplayer.lateJoin)throw Error(`This game does not allow joining after the start.`);if(this.roster.length>=this.runtime.multiplayer.players.max)throw Error(`The game is full.`);this.roster=[...this.roster,{id:e.id,name:e.name,isHost:!1,connected:!0}],this.broadcastPlayers()}removePlayer(e){if(e===this.authority)throw Error(`The host cannot be removed.`);this.disposeInstance(e),this.roster=this.roster.filter(t=>t.id!==e),this.broadcastPlayers()}renamePlayer(e,t){this.roster=this.roster.map(n=>n.id===e?{...n,name:t}:n),this.broadcastPlayers()}setConnected(e,t){let n=this.instances.get(e);n&&(n.connected=t),this.roster.some(t=>t.id===e)&&(this.roster=this.roster.map(n=>n.id===e?{...n,connected:t}:n),this.broadcastPlayers()),e===this.authority?this.setAuthorityConnected(t):t&&n&&this.callPlugin(e,e=>e.authorityChanged({connected:!0}))}get services(){return this.runtime.services.filter(e=>typeof this.options.services?.[e]==`function`)}get paused(){return this.pauseState.pausedAt!==null}get clock(){return{offsetMs:0,...this.pauseState}}pause(){!this.isStarted||this.isEnded||this.paused||(this.pauseState={...this.pauseState,pausedAt:Date.now()},this.broadcastClock())}resume(){this.paused&&(this.pauseState={pausedMs:this.pauseState.pausedMs+Math.max(0,Date.now()-this.pauseState.pausedAt),pausedAt:null},this.broadcastClock())}broadcastClock(){let e=this.clock;for(let t of this.instances.keys())this.callPlugin(t,t=>t.clockChanged(e));this.emit({type:`paused`,paused:this.paused,clock:{...this.pauseState}})}setConfig(e){this.hostConfig={...this.hostConfig,...e};for(let e of this.instances.keys())this.callPlugin(e,e=>e.configChanged(this.hostConfig))}async end(e=`closed`){this.isEnded||(this.isEnded=!0,e===`finished`?await this.discardSnapshot():await this.flushSnapshot(),await this.flushData(),await Promise.all([...this.instances.keys()].map(t=>this.callPlugin(t,t=>t.sessionEnded(e)))))}createHostApi(e){let t=(t,n)=>(async()=>{if(e.disposed)throw new r.ProtocolError(`SESSION_ENDED`,`This instance has been closed.`);if(this.isEnded&&t!==`reportError`)throw new r.ProtocolError(`SESSION_ENDED`,`The session has ended.`);return n()})().catch(n=>{let i=(0,r.toProtocolError)(n);throw this.emit({type:`rejected`,address:e.address,method:t,code:i.code,message:i.detail}),i}),n=()=>e.view===`solo`||e.view===`controller`,s=(t,n)=>{if(!n)throw new r.ProtocolError(`NOT_ALLOWED_IN_VIEW`,`${t} is not available in view "${e.view}".`)},c=t=>{if(e.address!==this.authority)throw new r.ProtocolError(`NOT_AUTHORITY`,`${t} may only be called by the authority.`)};return{hello:(...n)=>t(`hello`,async()=>{let[t]=(0,a.parseHostCall)(`hello`,n);if(e.greeted)throw new r.ProtocolError(`INVALID_ARGUMENT`,`hello may only be called once per instance.`);let i=(0,r.negotiateProtocolVersion)(t.protocol,r.PROTOCOL_VERSION);if(!i)throw new r.ProtocolError(`UNSUPPORTED_PROTOCOL`,`The plugin speaks protocol ${t.protocol}; this host supports ${r.PROTOCOL_VERSION}.`);return e.greeted=!0,t.plugin.id!==this.plugin.manifest.id&&this.emit({type:`pluginError`,address:e.address,code:`PLUGIN_ID_MISMATCH`,message:`The SDK reports plugin id "${t.plugin.id}", the manifest says "${this.plugin.manifest.id}".`}),this.buildInit(e,i)}),ready:(...n)=>t(`ready`,()=>{(0,a.parseHostCall)(`ready`,n),!e.ready&&(e.ready=!0,this.emit({type:`ready`,address:e.address}),e.address===this.authority&&(this.mode===`solo`&&!this.isStarted&&!e.resumed?(this.isStarted=!0,this.emit({type:`started`}),this.callPlugin(e.address,e=>e.start())):this.isStarted&&(this.resumeStartPending&&(this.resumeStartPending=!1,e.resumed||this.callPlugin(e.address,e=>e.start())),this.setAuthorityConnected(!0))))}),send:(...n)=>t(`send`,()=>{let[t]=(0,a.parseHostCall)(`send`,n);s(`send`,e.view!==`settings`);let i=(0,a.assertJsonWithin)(t.data,r.LIMITS.messageBytes,`MESSAGE_TOO_LARGE`,`message`),o=e.address===this.authority?1/Math.max(1,this.instances.size-1):1;if(!e.limiter.tryTake(o))throw new r.ProtocolError(`RATE_LIMITED`,`More than ${r.LIMITS.messagesPerSecond} messages per second.`);if(!e.connected)return;if(t.to===`authority`){let n=this.instances.get(this.authority);if(!n||!n.connected||!this.authorityConnected)throw new r.ProtocolError(`AUTHORITY_UNAVAILABLE`,`The host is not reachable right now.`);this.deliver(e.address,this.authority,t.data,i);return}let c=t.to===`all`?[...this.instances.keys()].filter(t=>t!==e.address&&t!==r.SETTINGS_ADDRESS):t.to.filter(e=>e!==r.SETTINGS_ADDRESS);for(let n of c)this.deliver(e.address,n,t.data,i)}),saveSnapshot:(...e)=>t(`saveSnapshot`,()=>{let[t]=(0,a.parseHostCall)(`saveSnapshot`,e);if(c(`saveSnapshot`),(0,a.assertJsonWithin)(t,r.LIMITS.snapshotBytes,`SNAPSHOT_TOO_LARGE`,`snapshot`),this.finished){this.finishedSnapshot=structuredClone(t);return}this.pendingSnapshot=structuredClone(t),this.snapshotTimer??=setTimeout(()=>void this.flushSnapshot(),1e3/r.LIMITS.snapshotsPerSecond)}),recordAnswer:(...n)=>t(`recordAnswer`,async()=>{let[t]=(0,a.parseHostCall)(`recordAnswer`,n),i=this.roster.some(t=>t.id===e.address)?e.address:null,o=t.playerId??i;if(!o)throw new r.ProtocolError(`INVALID_ARGUMENT`,`recordAnswer needs a playerId on the board.`);if(o!==i&&c(`recordAnswer for another player`),!this.roster.some(e=>e.id===o))throw new r.ProtocolError(`INVALID_ARGUMENT`,`Unknown player "${o}".`);let s=e.address===this.authority?1/Math.max(1,this.roster.length):1;if(!e.answerLimiter.tryTake(s))throw new r.ProtocolError(`RATE_LIMITED`,`More than ${r.LIMITS.answersPerSecond} answers per second.`);t.answer!==void 0&&(0,a.assertJsonWithin)(t.answer,r.LIMITS.answerBytes,`DATA_TOO_LARGE`,`answer`);let l=this.prepared.set.items.find(e=>e.id===t.itemId),u=e=>Array.isArray(e)?e.filter(e=>typeof e==`string`):[];if(!l){if(!t.item)throw new r.ProtocolError(`INVALID_ARGUMENT`,`Unknown item "${t.itemId}" (attach the item for a generated one).`);(0,a.assertJsonWithin)(t.item,r.LIMITS.generatedItemBytes,`DATA_TOO_LARGE`,`item`),this.emit({type:`answer`,playerId:o,record:null,answer:t,generated:!0,skills:u(t.item.skills),tags:u(t.item.tags)});return}let d=this.userKey(o),f=this.prepared.set.meta.id,p=await this.storage.loadProgress(d,f),{item:m,...h}=t,g=this.algorithm.apply(p[t.itemId],h,new Date,structuredClone(l));await this.storage.saveProgress(d,f,{[t.itemId]:g}),this.emit({type:`answer`,playerId:o,record:g,answer:h,generated:!1,skills:u(l.skills),tags:u(l.tags)})}),saveData:(...i)=>t(`saveData`,()=>{let[t,o]=(0,a.parseHostCall)(`saveData`,i);s(`saveData`,n()),(0,a.assertJsonWithin)(o,r.LIMITS.dataBytes,`DATA_TOO_LARGE`,`plugin data (${t})`);let c=`${e.address}|${t}`,l=this.pendingData.get(c);if(l)l.value=structuredClone(o);else{let n={playerId:e.address,scope:t,value:structuredClone(o),timer:setTimeout(()=>void this.flushData(c),1e3/r.LIMITS.dataWritesPerSecond)};this.pendingData.set(c,n)}}),updateSettings:(...n)=>t(`updateSettings`,()=>{let[t]=(0,a.parseHostCall)(`updateSettings`,n);s(`updateSettings`,e.view===`settings`);let{values:i,errors:o}=(0,r.resolveSettings)(this.runtime.settings,t.values);this.settingValues=i,this.settingsOk=t.valid&&o.length===0;let c=t.message??o[0];this.emit({type:`settings`,values:i,valid:this.settingsOk,...c&&{message:c}})}),getAsset:(...n)=>t(`getAsset`,async()=>{let[t,o]=(0,a.parseHostCall)(`getAsset`,n);if(!e.assetLimiter.tryTake())throw new r.ProtocolError(`RATE_LIMITED`,`More than ${r.LIMITS.assetsPerSecond} assets per second.`);let s=o?this.options.set.items.find(e=>e.id===o):void 0,c=(0,i.resolveAsset)(t,s,this.options.set.meta);if(!c)throw new r.ProtocolError(`ASSET_NOT_FOUND`,`Asset "${t}" does not exist.`);if(this.options.loadAsset)return this.options.loadAsset(t,o);if(/^https?:/i.test(c.value)){let e=await fetch(c.value);if(e.ok)return e.blob()}throw new r.ProtocolError(`ASSET_NOT_FOUND`,`Asset "${t}" cannot be loaded by this host.`)}),end:(...e)=>t(`end`,async()=>{let[t]=(0,a.parseHostCall)(`end`,e);c(`end`),!this.hasResult&&(this.hasResult=!0,await this.discardSnapshot(),this.emit({type:`result`,result:t}))}),reportError:(...n)=>t(`reportError`,()=>{let[t]=(0,a.parseHostCall)(`reportError`,n);e.errorLimiter.tryTake()&&this.emit({type:`pluginError`,address:e.address,code:t.code,message:t.message,...t.context&&{context:t.context}})}),service:(...n)=>t(`service`,async()=>{let[t,i]=(0,a.parseHostCall)(`service`,n),s=this.services.includes(t)?this.options.services[t]:void 0;if(!s)throw new r.ProtocolError(`SERVICE_UNAVAILABLE`,`Service "${t}" is not available here (declare it in the manifest "services"; this host offers: ${this.services.join(`, `)||`none`}).`);if((0,a.assertJsonWithin)(i,r.LIMITS.serviceBytes,`MESSAGE_TOO_LARGE`,`service ${t} request`),!e.serviceLimiter.tryTake())throw new r.ProtocolError(`RATE_LIMITED`,`More than ${r.LIMITS.servicesPerMinute} service calls per minute.`);let c=this.roster.some(t=>t.id===e.address)?e.address:null,l=await s(o(i),{playerId:c,address:e.address,pluginId:this.plugin.manifest.id,setId:this.prepared.set.meta.id});return(0,a.assertJsonWithin)(l??null,r.LIMITS.serviceResultBytes,`MESSAGE_TOO_LARGE`,`service ${t} result`),o(l??null)})}}async buildInit(e,t){let n=e.view===`solo`||e.view===`controller`,r=this.prepared.set.meta.id,i=n?this.userKey(e.address):null,a=this.plugin.manifest.id;e.address===this.authority&&await this.flushSnapshot();let o=e.address===this.authority?this.finished?structuredClone(this.finishedSnapshot):await this.storage.loadSnapshot(this.id):null;return e.resumed=o!==null,{protocol:t,host:this.options.host??{name:`@memizy/host-sdk`,version:`1.0.0-rc.6`},oqseVersion:`1.0`,features:[],session:{id:this.id,mode:this.mode,hostAs:this.hostAs,view:e.view,self:e.address,authority:this.authority,lateJoin:this.isStarted&&e.view!==`settings`},players:this.roster,set:structuredClone(this.mode===`multiplayer`&&e.address!==this.authority?this.prepared.publicSet:this.prepared.set),settings:{...this.settingValues},config:this.hostConfig,clock:this.clock,services:this.services,progress:i?await this.storage.loadProgress(i,r):{},data:i?{plugin:this.pendingDataValue(e.address,`plugin`)??await this.storage.loadData(i,a,`plugin`,r)??null,set:this.pendingDataValue(e.address,`set`)??await this.storage.loadData(i,a,`set`,r)??null}:{plugin:null,set:null},snapshot:o}}userKey(e){return this.options.userKeyFor?.(e)??e}deliver(e,t,n,r){let i=this.instances.get(t);if(!i||!i.connected||!i.plugin)return;this.emit({type:`traffic`,from:e,to:t,bytes:r,data:n});let a=structuredClone(n);setTimeout(()=>void this.callPlugin(t,t=>t.deliver({from:e,data:a,sentAt:Date.now()})),0)}broadcastPlayers(){this.emit({type:`players`,players:this.roster});for(let e of this.instances.keys())this.callPlugin(e,e=>e.playersChanged(this.roster))}setAuthorityConnected(e){if(this.authorityConnected!==e){this.authorityConnected=e,this.emit({type:`authority`,connected:e});for(let t of this.instances.keys())t!==this.authority&&t!==r.SETTINGS_ADDRESS&&this.callPlugin(t,t=>t.authorityChanged({connected:e}))}}async callPlugin(e,t){let n=this.instances.get(e);if(n?.plugin&&!n.disposed)try{await t(n.plugin)}catch(t){this.emit({type:`pluginError`,address:e,code:`PLUGIN_CALL_FAILED`,message:(0,r.toProtocolError)(t).detail})}}async discardSnapshot(){this.finished||(this.finished=!0,clearTimeout(this.snapshotTimer),this.snapshotTimer=void 0,this.finishedSnapshot=this.pendingSnapshot===void 0?await this.storage.loadSnapshot(this.id):this.pendingSnapshot,this.pendingSnapshot=void 0,await this.storage.deleteSnapshot?.(this.id))}async flushSnapshot(){if(clearTimeout(this.snapshotTimer),this.snapshotTimer=void 0,this.pendingSnapshot===void 0||this.finished)return;let e=this.pendingSnapshot;this.pendingSnapshot=void 0,await this.storage.saveSnapshot(this.id,e),this.finished&&await this.storage.deleteSnapshot?.(this.id)}pendingDataValue(e,t){return this.pendingData.get(`${e}|${t}`)?.value}async flushData(e){let t=e?[[e,this.pendingData.get(e)]]:[...this.pendingData.entries()];for(let[e,n]of t)n&&(clearTimeout(n.timer),this.pendingData.delete(e),await this.storage.saveData(this.userKey(n.playerId),this.plugin.manifest.id,n.scope,this.prepared.set.meta.id,n.value))}};function c(e){return new Promise(t=>setTimeout(t,Math.max(0,e)))}exports.LocalSession=s;
+require("./version.cjs");const e=require("./plugin.cjs"),t=require("./learning.cjs"),n=require("./storage.cjs");let r=require("@memizy/protocol"),i=require("@memizy/oqse"),a=require("@memizy/protocol/internal");function o(e){try{return structuredClone(e)}catch{return JSON.parse(JSON.stringify(e))}}var s=class{id;seed;plugin;runtime;mode;hostAs;authority;prepared;roster;settingValues;settingsOk=!0;hostConfig;isStarted=!1;isEnded=!1;pauseState={pausedMs:0,pausedAt:null};options;storage;algorithm;instances=new Map;listeners=new Set;authorityConnected=!0;startPromise=null;resumeStartPending=!1;pendingSnapshot=void 0;finished=!1;hasResult=!1;finishedSnapshot=null;snapshotTimer;pendingData=new Map;get players(){return this.roster}get settings(){return this.settingValues}get settingsValid(){return this.settingsOk}get config(){return this.hostConfig}get started(){return this.isStarted}get ended(){return this.isEnded}constructor(i){if(this.options=i,this.id=i.sessionId??`session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2,8)}`,this.seed=i.seed??l(),this.plugin=i.plugin,this.runtime=i.plugin.runtime,this.mode=i.mode,this.storage=i.storage??new n.MemoryStorage,this.algorithm=i.algorithm??t.leitner,this.hostConfig={locale:i.locale??`en`,theme:i.theme??`light`},i.mode===`solo`){if(!this.runtime.solo)throw Error(`The plugin does not support solo mode.`);this.hostAs=null}else{if(!this.runtime.multiplayer)throw Error(`The plugin does not support multiplayer.`);let e=i.hostAs??this.runtime.multiplayer.hostAs[0];if(!this.runtime.multiplayer.hostAs.includes(e))throw Error(`The plugin does not support hostAs "${e}".`);this.hostAs=e}let a=i.players??(i.mode===`solo`?[{id:`player`,name:`Player`,isHost:!0}]:[]);if(i.mode===`solo`&&a.length!==1)throw Error(`A solo session has exactly one player.`);if(new Set(a.map(e=>e.id)).size!==a.length)throw Error(`Player IDs must be unique.`);if(a.some(e=>e.id===r.BOARD_ADDRESS||e.id===r.SETTINGS_ADDRESS||e.id===`server`))throw Error(`Player IDs "board", "settings" and "server" are reserved.`);if(this.roster=a.map(e=>({id:e.id,name:e.name,isHost:i.mode===`solo`?!0:e.isHost??!1,connected:!0})),i.mode===`solo`)this.authority=this.roster[0].id;else if(this.hostAs===`presenter`)this.authority=r.BOARD_ADDRESS;else{let e=this.roster.find(e=>e.isHost);if(!e)throw Error(`With hostAs "player", one player must have isHost: true.`);this.authority=e.id}let s=(0,r.resolveSettings)(this.runtime.settings,i.settings??{},this.runtime.unknownSettings);if(s.errors.length>0)throw Error(`Invalid settings: ${s.errors.join(`; `)}`);this.settingValues=s.values;let c=i.shuffleSeed===null?void 0:i.shuffleSeed??l();this.prepared=e.prepareSetForPlugin(o(i.set),i.plugin.manifest,{seed:c}),i.restore&&(this.isStarted=!0,this.resumeStartPending=!0),i.clock&&(this.pauseState={pausedMs:i.clock.pausedMs??0,pausedAt:i.clock.pausedAt??null})}on(e){return this.listeners.add(e),()=>this.listeners.delete(e)}emit(e){for(let t of this.listeners)try{t(e)}catch(e){console.error(`[memizy host] session listener failed:`,e)}}viewOf(e){return e===r.SETTINGS_ADDRESS?`settings`:this.mode===`solo`?`solo`:e===r.BOARD_ADDRESS?`board`:`controller`}addresses(){return[...this.hostAs===`presenter`?[r.BOARD_ADDRESS]:[],...this.roster.map(e=>e.id)]}async connect(e,t,n={}){let i=this.viewOf(e);if(i===`settings`){if(!this.runtime.multiplayer||!this.runtime.settingsScreen)throw Error(`The plugin has no settings screen (settingsScreen).`);if(this.isStarted)throw Error(`The settings screen is only available before the game starts.`)}else if(!this.addresses().includes(e))throw Error(`Unknown address "${e}" in this session.`);if(this.isEnded)throw Error(`The session has ended.`);this.disposeInstance(e);let o={address:e,view:i,hostApi:void 0,endpoint:t,onDispose:n.onDispose,plugin:null,ready:!1,connected:!0,disposed:!1,resumed:!1,greeted:!1,limiter:new a.RateLimiter(r.LIMITS.messagesPerSecond,r.LIMITS.messageBurst),serviceLimiter:new a.RateLimiter(r.LIMITS.servicesPerMinute/60,10),answerLimiter:new a.RateLimiter(r.LIMITS.answersPerSecond,r.LIMITS.answerBurst),assetLimiter:new a.RateLimiter(r.LIMITS.assetsPerSecond,r.LIMITS.assetBurst),errorLimiter:new a.RateLimiter(r.LIMITS.errorReportsPerSecond,r.LIMITS.errorReportBurst)};o.hostApi=this.createHostApi(o),this.instances.set(e,o),e===this.authority&&this.isStarted&&this.setAuthorityConnected(!1);try{o.plugin=await t(o.hostApi)}catch(e){if(o.disposed)return o;throw e}return o}async reload(e){let t=this.instances.get(e);if(!t)throw Error(`No instance at "${e}".`);return e===this.authority&&await this.flushSnapshot(),this.connect(e,t.endpoint,{onDispose:t.onDispose})}disconnect(e){this.disposeInstance(e),e===this.authority&&this.isStarted&&this.setAuthorityConnected(!1)}disposeInstance(e){let t=this.instances.get(e);if(t){t.disposed=!0,this.instances.delete(e);try{t.onDispose?.()}catch(e){console.warn(`[memizy host] dispose failed:`,e)}}}getInstance(e){return this.instances.get(e)}start(){if(this.mode===`solo`||this.isStarted&&!this.startPromise)return Promise.resolve();if(!this.settingsOk)return Promise.reject(Error(`The settings are not valid.`));let e=this.roster.length,t=this.runtime.multiplayer.players;return e<t.min||e>t.max?Promise.reject(Error(`This plugin needs ${t.min}–${t.max} players (now ${e}).`)):(this.startPromise??=this.runStart(),this.startPromise)}async runStart(){this.disposeInstance(r.SETTINGS_ADDRESS);let e=Date.now()+(this.options.readyTimeoutMs??15e3),t=()=>[...this.instances.values()].every(e=>e.ready),n=()=>this.instances.get(this.authority)?.ready===!0;for(;!(t()&&n())&&(Date.now()<e||!n());){if(this.isEnded)return;await c(25)}let i=this.options.countdownMs??3e3;for(let e=Math.ceil(i/1e3);e>0;e--)this.emit({type:`countdown`,secondsLeft:e}),await c(Math.min(1e3,i-(Math.ceil(i/1e3)-e)*1e3));this.isEnded||(this.isStarted=!0,this.emit({type:`started`}),await this.callPlugin(this.authority,e=>e.start()))}addPlayer(e){if(this.mode===`solo`)throw Error(`Players cannot join a solo session.`);if(this.roster.some(t=>t.id===e.id)||[r.BOARD_ADDRESS,r.SETTINGS_ADDRESS,`server`].includes(e.id))throw Error(`Player ID "${e.id}" is already used or reserved.`);if(this.isStarted&&!this.runtime.multiplayer.lateJoin)throw Error(`This game does not allow joining after the start.`);if(this.roster.length>=this.runtime.multiplayer.players.max)throw Error(`The game is full.`);this.roster=[...this.roster,{id:e.id,name:e.name,isHost:!1,connected:!0}],this.broadcastPlayers()}removePlayer(e){if(e===this.authority)throw Error(`The host cannot be removed.`);this.disposeInstance(e),this.roster=this.roster.filter(t=>t.id!==e),this.broadcastPlayers()}renamePlayer(e,t){this.roster=this.roster.map(n=>n.id===e?{...n,name:t}:n),this.broadcastPlayers()}setConnected(e,t){let n=this.instances.get(e);n&&(n.connected=t),this.roster.some(t=>t.id===e)&&(this.roster=this.roster.map(n=>n.id===e?{...n,connected:t}:n),this.broadcastPlayers()),e===this.authority?this.setAuthorityConnected(t):t&&n&&this.callPlugin(e,e=>e.authorityChanged({connected:!0}))}get services(){return this.runtime.services.filter(e=>typeof this.options.services?.[e]==`function`)}get paused(){return this.pauseState.pausedAt!==null}get clock(){return{offsetMs:0,...this.pauseState}}pause(){!this.isStarted||this.isEnded||this.paused||(this.pauseState={...this.pauseState,pausedAt:Date.now()},this.broadcastClock())}resume(){this.paused&&(this.pauseState={pausedMs:this.pauseState.pausedMs+Math.max(0,Date.now()-this.pauseState.pausedAt),pausedAt:null},this.broadcastClock())}broadcastClock(){let e=this.clock;for(let t of this.instances.keys())this.callPlugin(t,t=>t.clockChanged(e));this.emit({type:`paused`,paused:this.paused,clock:{...this.pauseState}})}setConfig(e){this.hostConfig={...this.hostConfig,...e};for(let e of this.instances.keys())this.callPlugin(e,e=>e.configChanged(this.hostConfig))}async end(e=`closed`){this.isEnded||(this.isEnded=!0,e===`finished`?await this.discardSnapshot():await this.flushSnapshot(),await this.flushData(),await Promise.all([...this.instances.keys()].map(t=>this.callPlugin(t,t=>t.sessionEnded(e)))))}createHostApi(e){let t=(t,n)=>(async()=>{if(e.disposed)throw new r.ProtocolError(`SESSION_ENDED`,`This instance has been closed.`);if(this.isEnded&&t!==`reportError`)throw new r.ProtocolError(`SESSION_ENDED`,`The session has ended.`);return n()})().catch(n=>{let i=(0,r.toProtocolError)(n);throw this.emit({type:`rejected`,address:e.address,method:t,code:i.code,message:i.detail}),i}),n=()=>e.view===`solo`||e.view===`controller`,s=(t,n)=>{if(!n)throw new r.ProtocolError(`NOT_ALLOWED_IN_VIEW`,`${t} is not available in view "${e.view}".`)},c=t=>{if(e.address!==this.authority)throw new r.ProtocolError(`NOT_AUTHORITY`,`${t} may only be called by the authority.`)};return{hello:(...n)=>t(`hello`,async()=>{let[t]=(0,a.parseHostCall)(`hello`,n);if(e.greeted)throw new r.ProtocolError(`INVALID_ARGUMENT`,`hello may only be called once per instance.`);let i=(0,r.negotiateProtocolVersion)(t.protocol,r.PROTOCOL_VERSION);if(!i)throw new r.ProtocolError(`UNSUPPORTED_PROTOCOL`,`The plugin speaks protocol ${t.protocol}; this host supports ${r.PROTOCOL_VERSION}.`);return e.greeted=!0,t.plugin.id!==this.plugin.manifest.id&&this.emit({type:`pluginError`,address:e.address,code:`PLUGIN_ID_MISMATCH`,message:`The SDK reports plugin id "${t.plugin.id}", the manifest says "${this.plugin.manifest.id}".`}),this.buildInit(e,i)}),ready:(...n)=>t(`ready`,()=>{(0,a.parseHostCall)(`ready`,n),!e.ready&&(e.ready=!0,this.emit({type:`ready`,address:e.address}),e.address===this.authority&&(this.mode===`solo`&&!this.isStarted&&!e.resumed?(this.isStarted=!0,this.emit({type:`started`}),this.callPlugin(e.address,e=>e.start())):this.isStarted&&(this.resumeStartPending&&(this.resumeStartPending=!1,e.resumed||this.callPlugin(e.address,e=>e.start())),this.setAuthorityConnected(!0))))}),send:(...n)=>t(`send`,()=>{let[t]=(0,a.parseHostCall)(`send`,n);s(`send`,e.view!==`settings`);let i=(0,a.assertJsonWithin)(t.data,r.LIMITS.messageBytes,`MESSAGE_TOO_LARGE`,`message`),o=e.address===this.authority?1/Math.max(1,this.instances.size-1):1;if(!e.limiter.tryTake(o))throw new r.ProtocolError(`RATE_LIMITED`,`More than ${r.LIMITS.messagesPerSecond} messages per second.`);if(!e.connected)return;if(t.to===`authority`){let n=this.instances.get(this.authority);if(!n||!n.connected||!this.authorityConnected)throw new r.ProtocolError(`AUTHORITY_UNAVAILABLE`,`The host is not reachable right now.`);this.deliver(e.address,this.authority,t.data,i);return}let c=t.to===`all`?[...this.instances.keys()].filter(t=>t!==e.address&&t!==r.SETTINGS_ADDRESS):t.to.filter(e=>e!==r.SETTINGS_ADDRESS);for(let n of c)this.deliver(e.address,n,t.data,i)}),saveSnapshot:(...e)=>t(`saveSnapshot`,()=>{let[t]=(0,a.parseHostCall)(`saveSnapshot`,e);if(c(`saveSnapshot`),(0,a.assertJsonWithin)(t,r.LIMITS.snapshotBytes,`SNAPSHOT_TOO_LARGE`,`snapshot`),this.finished){this.finishedSnapshot=structuredClone(t);return}this.pendingSnapshot=structuredClone(t),this.snapshotTimer??=setTimeout(()=>void this.flushSnapshot(),1e3/r.LIMITS.snapshotsPerSecond)}),recordAnswer:(...n)=>t(`recordAnswer`,async()=>{let[t]=(0,a.parseHostCall)(`recordAnswer`,n),i=this.roster.some(t=>t.id===e.address)?e.address:null,o=t.playerId??i;if(!o)throw new r.ProtocolError(`INVALID_ARGUMENT`,`recordAnswer needs a playerId on the board.`);if(c(`recordAnswer`),!this.roster.some(e=>e.id===o))throw new r.ProtocolError(`INVALID_ARGUMENT`,`Unknown player "${o}".`);let s=e.address===this.authority?1/Math.max(1,this.roster.length):1;if(!e.answerLimiter.tryTake(s))throw new r.ProtocolError(`RATE_LIMITED`,`More than ${r.LIMITS.answersPerSecond} answers per second.`);t.answer!==void 0&&(0,a.assertJsonWithin)(t.answer,r.LIMITS.answerBytes,`DATA_TOO_LARGE`,`answer`);let l=this.prepared.set.items.find(e=>e.id===t.itemId),u=e=>Array.isArray(e)?e.filter(e=>typeof e==`string`):[];if(!l){if(!t.item)throw new r.ProtocolError(`INVALID_ARGUMENT`,`Unknown item "${t.itemId}" (attach the item for a generated one).`);(0,a.assertJsonWithin)(t.item,r.LIMITS.generatedItemBytes,`DATA_TOO_LARGE`,`item`),this.emit({type:`answer`,playerId:o,setId:this.prepared.set.meta.id,record:null,answer:t,generated:!0,ungraded:!1,skills:u(t.item.skills),tags:u(t.item.tags)});return}let d=this.prepared.set.meta.id;if(l.type===`open-ended`){let{item:e,...n}=t;this.emit({type:`answer`,playerId:o,setId:d,record:null,answer:n,generated:!1,ungraded:!0,skills:u(l.skills),tags:u(l.tags)});return}let f=this.userKey(o),p=await this.storage.loadProgress(f,d),{item:m,...h}=t,g=this.algorithm.apply(p[t.itemId],h,new Date,structuredClone(l));await this.storage.saveProgress(f,d,{[t.itemId]:g}),this.emit({type:`answer`,playerId:o,setId:d,record:g,answer:h,generated:!1,ungraded:!1,skills:u(l.skills),tags:u(l.tags)})}),saveData:(...i)=>t(`saveData`,()=>{let[t,o]=(0,a.parseHostCall)(`saveData`,i);s(`saveData`,n()),(0,a.assertJsonWithin)(o,r.LIMITS.dataBytes,`DATA_TOO_LARGE`,`plugin data (${t})`);let c=`${e.address}|${t}`,l=this.pendingData.get(c);if(l)l.value=structuredClone(o);else{let n={playerId:e.address,scope:t,value:structuredClone(o),timer:setTimeout(()=>void this.flushData(c),1e3/r.LIMITS.dataWritesPerSecond)};this.pendingData.set(c,n)}}),updateSettings:(...n)=>t(`updateSettings`,()=>{let[t]=(0,a.parseHostCall)(`updateSettings`,n);s(`updateSettings`,e.view===`settings`);let{values:i,errors:o}=(0,r.resolveSettings)(this.runtime.settings,t.values,this.runtime.unknownSettings);this.settingValues=i,this.settingsOk=t.valid&&o.length===0;let c=t.message??o[0];this.emit({type:`settings`,values:i,valid:this.settingsOk,...c&&{message:c}})}),getAsset:(...n)=>t(`getAsset`,async()=>{let[t,o]=(0,a.parseHostCall)(`getAsset`,n);if(!e.assetLimiter.tryTake())throw new r.ProtocolError(`RATE_LIMITED`,`More than ${r.LIMITS.assetsPerSecond} assets per second.`);let s=this.mode===`multiplayer`&&e.address!==this.authority?this.prepared.publicSet:this.prepared.set,c=o?s.items.find(e=>e.id===o):void 0,l=(0,i.resolveAsset)(t,c,s.meta);if(!l)throw new r.ProtocolError(`ASSET_NOT_FOUND`,`Asset "${t}" does not exist.`);if(this.options.loadAsset)return this.options.loadAsset(t,o);if(/^https?:/i.test(l.value)){let e=await fetch(l.value);if(e.ok)return e.blob()}throw new r.ProtocolError(`ASSET_NOT_FOUND`,`Asset "${t}" cannot be loaded by this host.`)}),end:(...e)=>t(`end`,async()=>{let[t]=(0,a.parseHostCall)(`end`,e);c(`end`),!this.hasResult&&(this.hasResult=!0,await this.discardSnapshot(),this.emit({type:`result`,result:t}))}),reportError:(...n)=>t(`reportError`,()=>{let[t]=(0,a.parseHostCall)(`reportError`,n);e.errorLimiter.tryTake()&&this.emit({type:`pluginError`,address:e.address,code:t.code,message:t.message,...t.context&&{context:t.context}})}),service:(...n)=>t(`service`,async()=>{let[t,i]=(0,a.parseHostCall)(`service`,n),s=this.services.includes(t)?this.options.services[t]:void 0;if(!s)throw new r.ProtocolError(`SERVICE_UNAVAILABLE`,`Service "${t}" is not available here (declare it in the manifest "services"; this host offers: ${this.services.join(`, `)||`none`}).`);if((0,a.assertJsonWithin)(i,r.LIMITS.serviceBytes,`MESSAGE_TOO_LARGE`,`service ${t} request`),!e.serviceLimiter.tryTake())throw new r.ProtocolError(`RATE_LIMITED`,`More than ${r.LIMITS.servicesPerMinute} service calls per minute.`);let c=this.roster.some(t=>t.id===e.address)?e.address:null,l=await s(o(i),{playerId:c,address:e.address,pluginId:this.plugin.manifest.id,setId:this.prepared.set.meta.id});return(0,a.assertJsonWithin)(l??null,r.LIMITS.serviceResultBytes,`MESSAGE_TOO_LARGE`,`service ${t} result`),o(l??null)})}}async buildInit(e,t){let n=e.view===`solo`||e.view===`controller`,r=this.prepared.set.meta.id,i=n?this.userKey(e.address):null,a=this.plugin.manifest.id;e.address===this.authority&&await this.flushSnapshot();let o=e.address===this.authority?this.finished?structuredClone(this.finishedSnapshot):await this.storage.loadSnapshot(this.id):null;return e.resumed=o!==null,{protocol:t,host:this.options.host??{name:`@memizy/host-sdk`,version:`1.0.0-rc.7`},oqseVersion:`1.0`,features:[],session:{id:this.id,mode:this.mode,hostAs:this.hostAs,view:e.view,self:e.address,authority:this.authority,lateJoin:this.isStarted&&e.view!==`settings`},players:this.roster,set:structuredClone(this.mode===`multiplayer`&&e.address!==this.authority?this.prepared.publicSet:this.prepared.set),settings:{...this.settingValues},config:this.hostConfig,clock:this.clock,services:this.services,progress:i?await this.storage.loadProgress(i,r):{},data:i?{plugin:this.pendingDataValue(e.address,`plugin`)??await this.storage.loadData(i,a,`plugin`,r)??null,set:this.pendingDataValue(e.address,`set`)??await this.storage.loadData(i,a,`set`,r)??null}:{plugin:null,set:null},snapshot:o,...e.address===this.authority&&{seed:this.seed}}}userKey(e){return this.options.userKeyFor?.(e)??e}deliver(e,t,n,r){let i=this.instances.get(t);if(!i||!i.connected||!i.plugin)return;this.emit({type:`traffic`,from:e,to:t,bytes:r,data:n});let a=structuredClone(n);setTimeout(()=>void this.callPlugin(t,t=>t.deliver({from:e,data:a,sentAt:Date.now()})),0)}broadcastPlayers(){this.emit({type:`players`,players:this.roster});for(let e of this.instances.keys())this.callPlugin(e,e=>e.playersChanged(this.roster))}setAuthorityConnected(e){if(this.authorityConnected!==e){this.authorityConnected=e,this.emit({type:`authority`,connected:e});for(let t of this.instances.keys())t!==this.authority&&t!==r.SETTINGS_ADDRESS&&this.callPlugin(t,t=>t.authorityChanged({connected:e}))}}async callPlugin(e,t){let n=this.instances.get(e);if(n?.plugin&&!n.disposed)try{await t(n.plugin)}catch(t){this.emit({type:`pluginError`,address:e,code:`PLUGIN_CALL_FAILED`,message:(0,r.toProtocolError)(t).detail})}}async discardSnapshot(){this.finished||(this.finished=!0,clearTimeout(this.snapshotTimer),this.snapshotTimer=void 0,this.finishedSnapshot=this.pendingSnapshot===void 0?await this.storage.loadSnapshot(this.id):this.pendingSnapshot,this.pendingSnapshot=void 0,await this.storage.deleteSnapshot?.(this.id))}async flushSnapshot(){if(clearTimeout(this.snapshotTimer),this.snapshotTimer=void 0,this.pendingSnapshot===void 0||this.finished)return;let e=this.pendingSnapshot;this.pendingSnapshot=void 0,await this.storage.saveSnapshot(this.id,e),this.finished&&await this.storage.deleteSnapshot?.(this.id)}pendingDataValue(e,t){return this.pendingData.get(`${e}|${t}`)?.value}async flushData(e){let t=e?[[e,this.pendingData.get(e)]]:[...this.pendingData.entries()];for(let[e,n]of t)n&&(clearTimeout(n.timer),this.pendingData.delete(e),await this.storage.saveData(this.userKey(n.playerId),this.plugin.manifest.id,n.scope,this.prepared.set.meta.id,n.value))}};function c(e){return new Promise(t=>setTimeout(t,Math.max(0,e)))}function l(){let e=new Uint8Array(16);return globalThis.crypto.getRandomValues(e),[...e].map(e=>e.toString(16).padStart(2,`0`)).join(``)}exports.LocalSession=s;

package/dist/session.js

@@ -15,6 +15,7 @@ function h(e) {
 }
 var g = class {
 	id;
+	seed;
 	plugin;
 	runtime;
 	mode;
@@ -64,7 +65,7 @@ var g = class {
 		return this.isEnded;
 	}
 	constructor(i) {
-		if (this.options = i, this.id = i.sessionId ?? `session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`, this.plugin = i.plugin, this.runtime = i.plugin.runtime, this.mode = i.mode, this.storage = i.storage ?? new n(), this.algorithm = i.algorithm ?? t, this.hostConfig = {
+		if (this.options = i, this.id = i.sessionId ?? `session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`, this.seed = i.seed ?? v(), this.plugin = i.plugin, this.runtime = i.plugin.runtime, this.mode = i.mode, this.storage = i.storage ?? new n(), this.algorithm = i.algorithm ?? t, this.hostConfig = {
 			locale: i.locale ?? "en",
 			theme: i.theme ?? "light"
 		}, i.mode === "solo") {
@@ -96,10 +97,10 @@ var g = class {
 			if (!e) throw Error("With hostAs \"player\", one player must have isHost: true.");
 			this.authority = e.id;
 		}
-		let o = l(this.runtime.settings, i.settings ?? {});
+		let o = l(this.runtime.settings, i.settings ?? {}, this.runtime.unknownSettings);
 		if (o.errors.length > 0) throw Error(`Invalid settings: ${o.errors.join("; ")}`);
 		this.settingValues = o.values;
-		let c = i.shuffleSeed === null ? void 0 : i.shuffleSeed ?? this.id;
+		let c = i.shuffleSeed === null ? void 0 : i.shuffleSeed ?? v();
 		this.prepared = e(h(i.set), i.plugin.manifest, { seed: c }), i.restore && (this.isStarted = !0, this.resumeStartPending = !0), i.clock && (this.pauseState = {
 			pausedMs: i.clock.pausedMs ?? 0,
 			pausedAt: i.clock.pausedAt ?? null
@@ -338,7 +339,7 @@ var g = class {
 			recordAnswer: (...n) => t("recordAnswer", async () => {
 				let [t] = m("recordAnswer", n), r = this.roster.some((t) => t.id === e.address) ? e.address : null, a = t.playerId ?? r;
 				if (!a) throw new o("INVALID_ARGUMENT", "recordAnswer needs a playerId on the board.");
-				if (a !== r && f("recordAnswer for another player"), !this.roster.some((e) => e.id === a)) throw new o("INVALID_ARGUMENT", `Unknown player "${a}".`);
+				if (f("recordAnswer"), !this.roster.some((e) => e.id === a)) throw new o("INVALID_ARGUMENT", `Unknown player "${a}".`);
 				let s = e.address === this.authority ? 1 / Math.max(1, this.roster.length) : 1;
 				if (!e.answerLimiter.tryTake(s)) throw new o("RATE_LIMITED", `More than ${i.answersPerSecond} answers per second.`);
 				t.answer !== void 0 && p(t.answer, i.answerBytes, "DATA_TOO_LARGE", "answer");
@@ -348,21 +349,41 @@ var g = class {
 					p(t.item, i.generatedItemBytes, "DATA_TOO_LARGE", "item"), this.emit({
 						type: "answer",
 						playerId: a,
+						setId: this.prepared.set.meta.id,
 						record: null,
 						answer: t,
 						generated: !0,
+						ungraded: !1,
 						skills: l(t.item.skills),
 						tags: l(t.item.tags)
 					});
 					return;
 				}
-				let u = this.userKey(a), d = this.prepared.set.meta.id, h = await this.storage.loadProgress(u, d), { item: g, ..._ } = t, v = this.algorithm.apply(h[t.itemId], _, /* @__PURE__ */ new Date(), structuredClone(c));
-				await this.storage.saveProgress(u, d, { [t.itemId]: v }), this.emit({
+				let u = this.prepared.set.meta.id;
+				if (c.type === "open-ended") {
+					let { item: e, ...n } = t;
+					this.emit({
+						type: "answer",
+						playerId: a,
+						setId: u,
+						record: null,
+						answer: n,
+						generated: !1,
+						ungraded: !0,
+						skills: l(c.skills),
+						tags: l(c.tags)
+					});
+					return;
+				}
+				let d = this.userKey(a), h = await this.storage.loadProgress(d, u), { item: g, ..._ } = t, v = this.algorithm.apply(h[t.itemId], _, /* @__PURE__ */ new Date(), structuredClone(c));
+				await this.storage.saveProgress(d, u, { [t.itemId]: v }), this.emit({
 					type: "answer",
 					playerId: a,
+					setId: u,
 					record: v,
 					answer: _,
 					generated: !1,
+					ungraded: !1,
 					skills: l(c.skills),
 					tags: l(c.tags)
 				});
@@ -385,7 +406,7 @@ var g = class {
 			updateSettings: (...n) => t("updateSettings", () => {
 				let [t] = m("updateSettings", n);
 				r("updateSettings", e.view === "settings");
-				let { values: i, errors: a } = l(this.runtime.settings, t.values);
+				let { values: i, errors: a } = l(this.runtime.settings, t.values, this.runtime.unknownSettings);
 				this.settingValues = i, this.settingsOk = t.valid && a.length === 0;
 				let o = t.message ?? a[0];
 				this.emit({
@@ -398,11 +419,11 @@ var g = class {
 			getAsset: (...n) => t("getAsset", async () => {
 				let [t, r] = m("getAsset", n);
 				if (!e.assetLimiter.tryTake()) throw new o("RATE_LIMITED", `More than ${i.assetsPerSecond} assets per second.`);
-				let a = r ? this.options.set.items.find((e) => e.id === r) : void 0, s = d(t, a, this.options.set.meta);
-				if (!s) throw new o("ASSET_NOT_FOUND", `Asset "${t}" does not exist.`);
+				let a = this.mode === "multiplayer" && e.address !== this.authority ? this.prepared.publicSet : this.prepared.set, s = r ? a.items.find((e) => e.id === r) : void 0, c = d(t, s, a.meta);
+				if (!c) throw new o("ASSET_NOT_FOUND", `Asset "${t}" does not exist.`);
 				if (this.options.loadAsset) return this.options.loadAsset(t, r);
-				if (/^https?:/i.test(s.value)) {
-					let e = await fetch(s.value);
+				if (/^https?:/i.test(c.value)) {
+					let e = await fetch(c.value);
 					if (e.ok) return e.blob();
 				}
 				throw new o("ASSET_NOT_FOUND", `Asset "${t}" cannot be loaded by this host.`);
@@ -446,7 +467,7 @@ var g = class {
 			protocol: t,
 			host: this.options.host ?? {
 				name: "@memizy/host-sdk",
-				version: "1.0.0-rc.6"
+				version: "1.0.0-rc.7"
 			},
 			oqseVersion: "1.0",
 			features: [],
@@ -473,7 +494,8 @@ var g = class {
 				plugin: null,
 				set: null
 			},
-			snapshot: o
+			snapshot: o,
+			...e.address === this.authority && { seed: this.seed }
 		};
 	}
 	userKey(e) {
@@ -544,5 +566,9 @@ var g = class {
 function _(e) {
 	return new Promise((t) => setTimeout(t, Math.max(0, e)));
 }
+function v() {
+	let e = /* @__PURE__ */ new Uint8Array(16);
+	return globalThis.crypto.getRandomValues(e), [...e].map((e) => e.toString(16).padStart(2, "0")).join("");
+}
 //#endregion
 export { g as LocalSession };

package/dist/src/learning.d.ts

@@ -6,6 +6,8 @@ export interface LearningAlgorithm {
     /**
      * The new progress record of the answered item. `item` is the item of the set with its
      * answers (type, difficulty, skills… for algorithms like FSRS); it may be ignored.
+     * Build it from `previous`: the learner's `starred` and fields of a later OQSEP version
+     * MUST stay (OQSEP "On unknown keys"); store `answer.answer` as `lastAnswer.answer`.
      */
     apply(previous: ProgressRecord | undefined, answer: AnswerRecord, now: Date, item: OQSEAnyItem): ProgressRecord;
 }

package/dist/src/plugin.d.ts

@@ -35,7 +35,7 @@ export interface PreparedSet {
 /**
  * Keeps only the item types the plugin declares and reports the OQSEM
  * handshake (`checkCompatibility`). The set should already be loaded with
- * `loadOQSEFile`. With a `seed` (normally the session id) the options, pairs
+ * `loadOQSEFile`. With a secret `seed` (random per game, never the session id) the options, pairs
  * and orders are shuffled once for the session (SPEC 4.4).
  */
 export declare function prepareSetForPlugin(file: OQSEFile, manifest: PluginManifest, options?: {

package/dist/src/session.d.ts

@@ -31,10 +31,17 @@ export interface SessionConfig {
     theme?: HostConfig['theme'];
     sessionId?: string;
     /**
-     * Seed of the display order of options, pairs… (SPEC 4.4; default: the session id).
-     * Pass the seed used for the relay bundle so all devices agree; `null` keeps the set's order.
+     * Secret seed of the display order of options, pairs… (SPEC 4.4; default: random). Pass the
+     * seed used for the relay bundle so all devices agree, and the same seed again to continue a
+     * saved game; `null` keeps the set's order. Never derive it from the session id or the PIN:
+     * a player could undo the shuffle.
      */
     shuffleSeed?: string | null;
+    /**
+     * Secret seed of the game's random numbers, given only to the authority (SPEC 4.2;
+     * default: 128 random bits). Pass one only to replay a game or in tests.
+     */
+    seed?: string;
     host?: {
         name: string;
         version: string;
@@ -84,14 +91,19 @@ export type SessionEvent = {
 }
 /**
  * A recorded answer. `record` is the updated learning progress (null for a generated item,
- * which is not repeated); `skills` / `tags` come from the item (for statistics).
+ * which is not repeated, and for an ungraded answer); `ungraded`: an answer that is not
+ * checked automatically (`open-ended`, SPEC 5.1) – kept for a teacher, repetition unchanged.
+ * `setId` + `answer.itemId` identify the item (OQSE: an item ID alone is not unique across
+ * sets); `skills` / `tags` come from the item (for statistics).
  */
  | {
     type: 'answer';
     playerId: string;
+    setId: string;
     record: ProgressRecord | null;
     answer: AnswerRecord;
     generated: boolean;
+    ungraded: boolean;
     skills: string[];
     tags: string[];
 }
@@ -142,6 +154,8 @@ export interface SessionInstance {
 }
 export declare class LocalSession {
     readonly id: string;
+    /** Secret seed of the game's random numbers (only the authority gets it). */
+    private readonly seed;
     readonly plugin: LoadedPlugin;
     readonly runtime: PluginRuntime;
     readonly mode: 'solo' | 'multiplayer';

package/dist/version.cjs

@@ -1 +1 @@
-var e=`1.0.0-rc.6`;exports.HOST_SDK_VERSION=e;
+var e=`1.0.0-rc.7`;exports.HOST_SDK_VERSION=e;

package/dist/version.js

@@ -1,4 +1,4 @@
 //#region src/version.ts
-var e = "1.0.0-rc.6";
+var e = "1.0.0-rc.7";
 //#endregion
 export { e as HOST_SDK_VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memizy/host-sdk",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0-rc.7",
   "description": "Run Memizy plugins: sandboxed iframes, protocol validation, sessions, storage hooks.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -28,12 +28,12 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@memizy/oqse": "^1.0.0-rc.6",
-    "@memizy/protocol": "^1.0.0-rc.6",
+    "@memizy/oqse": "^1.0.0-rc.7",
+    "@memizy/protocol": "^1.0.0-rc.7",
     "penpal": "^8.0.1"
   },
   "devDependencies": {
-    "@memizy/plugin-sdk": "^1.0.0-rc.6",
+    "@memizy/plugin-sdk": "^1.0.0-rc.7",
     "@types/node": "^25.6.0",
     "@types/ws": "^8",
     "jsdom": "^30.1.2",