Add aa-signal-protocol element for ESM signalling schedules

Declarative custom element that specifies when and how participants
are signalled in signal-contingent ESM/EMA studies. Supports fixed,
random, and stratified-random scheduling with time windows, weekend
overrides, exclusions, and a getSignallingTimes() method that computes
concrete signal times for external scheduling systems.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: b3008

src/customElements/aa-signal-protocol/aa-signal-protocol.ts

@@ -26,6 +26,7 @@ export { AAMemory } from './customElements/aa-memory/aa-memory';
 export { AASequence } from './customElements/aa-sequence/aa-sequence';
 export { AAJump } from './customElements/aa-sequence/aa-jump/aa-jump';
 export { AASession, type AASessionInput, type AASessionInputSubmitEventDetail } from './customElements/aa-session/aa-session';
+export { AASignalProtocol, type SignalProtocolConfig } from './customElements/aa-signal-protocol/aa-signal-protocol';
 export { AASlider } from './customElements/aa-slider/aa-slider';
 export { AATextAnswer } from './customElements/aa-text-answer/aa-text-answer';
 export { AAVariable } from './customElements/aa-variable/aa-variable';

src/index.ts

@@ -0,0 +1,130 @@
+import type { Meta, StoryObj } from "@storybook/web-components";
+import { html } from "lit";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
+
+const classicESM = `<aa-signal-protocol
+  name="classic-esm"
+  schedule-type="stratified-random"
+  signals-per-day="8"
+  window-start="09:00"
+  window-end="22:00"
+  min-interval="20min"
+  signal-expiry="15min"
+  reminder-after="5min"
+  study-days="14">
+  <aa-session name="daily-experience" should-run="false">
+    <template><div>Assessment content here</div></template>
+  </aa-session>
+</aa-signal-protocol>`;
+
+const weekdayWeekendSplit = `<aa-signal-protocol
+  name="work-stress"
+  schedule-type="stratified-random"
+  signals-per-day="6"
+  signal-windows="08:00-12:00;13:00-20:00"
+  min-interval="30min"
+  signal-expiry="20min"
+  weekend-signals-per-day="4"
+  weekend-signal-windows="10:00-21:00"
+  start-date="2025-09-01"
+  end-date="2025-09-21">
+  <aa-session name="work-stress-assessment" should-run="false">
+    <template><div>Assessment content here</div></template>
+  </aa-session>
+</aa-signal-protocol>`;
+
+const fixedDiaryPlusRandom = `<aa-signal-protocol
+  name="mixed-protocol"
+  schedule-type="stratified-random"
+  signals-per-day="5"
+  window-start="10:00"
+  window-end="20:00"
+  min-interval="30min"
+  fixed-times="07:30,22:00"
+  fixed-times-label="diary"
+  study-days="7">
+  <aa-session name="mood-diary" should-run="false">
+    <template><div>Assessment content here</div></template>
+  </aa-session>
+</aa-signal-protocol>`;
+
+const fixedTimeOnly = `<aa-signal-protocol
+  name="daily-diary"
+  schedule-type="fixed"
+  fixed-times="08:00,14:00,21:00"
+  signal-expiry="30min"
+  reminder-after="15min"
+  reminder-count="2"
+  active-days="weekdays"
+  study-days="21">
+  <aa-session name="diary-assessment" should-run="false">
+    <template><div>Assessment content here</div></template>
+  </aa-session>
+</aa-signal-protocol>`;
+
+function renderProtocolSummary(sourceCode: string) {
+  return html`
+    <div style="font-family: monospace; padding: 16px;">
+      <pre style="background: #f5f5f5; padding: 16px; border-radius: 4px; overflow-x: auto; white-space: pre-wrap;">${sourceCode}</pre>
+      ${unsafeHTML(sourceCode)}
+      <script type="module">
+        setTimeout(() => {
+          const protocol = document.querySelector('aa-signal-protocol');
+          if (protocol && protocol.getProtocol) {
+            const config = protocol.getProtocol();
+            const summary = document.getElementById('protocol-summary');
+            if (summary) {
+              summary.textContent = JSON.stringify(config, null, 2);
+            }
+          }
+        }, 100);
+      </script>
+      <h3 style="font-family: sans-serif; margin-top: 16px;">Parsed Protocol</h3>
+      <pre id="protocol-summary" style="background: #e8f5e9; padding: 16px; border-radius: 4px; overflow-x: auto; white-space: pre-wrap;"></pre>
+    </div>
+  `;
+}
+
+const meta = {
+  title: "Data & Utility/SignalProtocol",
+  tags: ["autodocs"],
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const ClassicStratifiedRandomESM: Story = {
+  render: () => renderProtocolSummary(classicESM),
+  parameters: {
+    docs: {
+      source: { code: classicESM, language: "html" },
+    },
+  },
+};
+
+export const WeekdayWeekendSplit: Story = {
+  render: () => renderProtocolSummary(weekdayWeekendSplit),
+  parameters: {
+    docs: {
+      source: { code: weekdayWeekendSplit, language: "html" },
+    },
+  },
+};
+
+export const FixedDiaryPlusRandomSignals: Story = {
+  render: () => renderProtocolSummary(fixedDiaryPlusRandom),
+  parameters: {
+    docs: {
+      source: { code: fixedDiaryPlusRandom, language: "html" },
+    },
+  },
+};
+
+export const FixedTimeOnly: Story = {
+  render: () => renderProtocolSummary(fixedTimeOnly),
+  parameters: {
+    docs: {
+      source: { code: fixedTimeOnly, language: "html" },
+    },
+  },
+};

src/stories/SignalProtocol.stories.ts

@@ -0,0 +1,14 @@
+import{b as t}from"./lit-element-BrtkDOYA.js";import{o as l}from"./unsafe-html-DX_ZMqK7.js";import"./directive-CF8sV3Lr.js";const e=`<aa-session name="choose-demo" debug>
+  <aa-variable name="score" value="75"></aa-variable>
+  <aa-choose name="grade" debug>
+    <aa-when test="score >= 90">
+      <aa-label>Grade: A — Excellent!</aa-label>
+    </aa-when>
+    <aa-when test="score >= 70">
+      <aa-label>Grade: B — Good job!</aa-label>
+    </aa-when>
+    <aa-otherwise>
+      <aa-label>Grade: C — Keep trying!</aa-label>
+    </aa-otherwise>
+  </aa-choose>
+</aa-session>`,m={title:"Control Flow/Choose",tags:["autodocs"],render:()=>t`${l(e)}`,parameters:{docs:{source:{code:e,language:"html"}}}},a={};var o,r,s;a.parameters={...a.parameters,docs:{...(o=a.parameters)==null?void 0:o.docs,source:{originalSource:"{}",...(s=(r=a.parameters)==null?void 0:r.docs)==null?void 0:s.source}}};const i=["Default"];export{a as Default,i as __namedExportsOrder,m as default};

storybook-static/assets/Choose.stories-BDFeRZB1.js

@@ -0,0 +1,32 @@
+import{b as x}from"./lit-element-BrtkDOYA.js";import{o as f}from"./unsafe-html-DX_ZMqK7.js";import"./directive-CF8sV3Lr.js";const b=(e,r,g)=>`<aa-session name="${e}">
+  <div style="display:flex; align-items:center; gap:12px;">
+    <button onclick="
+      var container = this.parentElement.querySelector('.result-container');
+      container.innerHTML = '';
+      var el = document.createElement('aa-function-random');
+      el.setAttribute('name', 'randomValue');
+      el.setAttribute('min', '${r}');
+      el.setAttribute('max', '${g}');
+      el.setAttribute('debug', '');
+      container.appendChild(el);
+      this.parentElement.querySelector('.result-value').textContent = el.value;
+    ">Generate</button>
+    <span>Result: <strong class="result-value">—</strong></span>
+    <span class="result-container" style="display:none;"></span>
+  </div>
+</aa-session>`,D={title:"Data & Utility/Function Random",tags:["autodocs"],render:e=>{const r=b("random-demo",e.min,e.max);return x`${f(r)}`},parameters:{docs:{source:{code:'<aa-function-random name="randomValue" min="1" max="100"></aa-function-random>',language:"html"}}}},a={args:{min:1,max:100}},n={args:{min:1,max:6}},t={args:{min:0,max:1}};var s,o,m;a.parameters={...a.parameters,docs:{...(s=a.parameters)==null?void 0:s.docs,source:{originalSource:`{
+  args: {
+    min: 1,
+    max: 100
+  }
+}`,...(m=(o=a.parameters)==null?void 0:o.docs)==null?void 0:m.source}}};var i,c,l;n.parameters={...n.parameters,docs:{...(i=n.parameters)==null?void 0:i.docs,source:{originalSource:`{
+  args: {
+    min: 1,
+    max: 6
+  }
+}`,...(l=(c=n.parameters)==null?void 0:c.docs)==null?void 0:l.source}}};var u,d,p;t.parameters={...t.parameters,docs:{...(u=t.parameters)==null?void 0:u.docs,source:{originalSource:`{
+  args: {
+    min: 0,
+    max: 1
+  }
+}`,...(p=(d=t.parameters)==null?void 0:d.docs)==null?void 0:p.source}}};const h=["Default","DiceRoll","CoinFlip"];export{t as CoinFlip,a as Default,n as DiceRoll,h as __namedExportsOrder,D as default};