@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

package/examples/components/comparison.mjs

@@ -0,0 +1,8 @@
+import { defineComponent, content } from '@shoalrun/cli/components';
+export default defineComponent({
+  attributes: { title: { type: 'string', required: true } },
+  children: 'required',
+  content({ attributes, children }) {
+    return content.component('Tabs', { label: attributes.title }, [children]);
+  }
+});

package/examples/components/components.json

@@ -0,0 +1,6 @@
+{
+  "apiVersion": 1,
+  "components": {
+    "Comparison": { "module": "./comparison.mjs" }
+  }
+}

package/examples/components/copy-text/LICENSE.react-dom.txt

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

package/examples/components/copy-text/LICENSE.react.txt

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

package/examples/components/copy-text/LICENSE.scheduler.txt

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

package/examples/components/copy-text/browser.jsx

@@ -0,0 +1,21 @@
+import React, { useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+
+export function enhance({ controls, content }) {
+  return new Promise((resolve, reject) => {
+    function CopyButton() {
+      const [message, setMessage] = useState('');
+      useEffect(() => { controls.hidden = false; resolve(); }, []);
+      async function copy() {
+        try {
+          await navigator.clipboard.writeText(content.innerText.trim());
+          setMessage('Copied.');
+        } catch {
+          setMessage('Copy failed. Select the text and copy it manually.');
+        }
+      }
+      return <><button type="button" onClick={copy}>Copy text</button>{' '}<span role="status">{message}</span></>;
+    }
+    createRoot(controls, { onUncaughtError: error => { controls.hidden = true; reject(error); } }).render(<CopyButton />);
+  });
+}

package/examples/components/copy-text/components.json

@@ -0,0 +1,6 @@
+{
+  "apiVersion": 1,
+  "components": {
+    "CopyText": { "module": "./plugin.mjs", "browser": "./browser.jsx" }
+  }
+}

package/examples/components/copy-text/package-lock.json

@@ -0,0 +1,41 @@
+{
+  "name": "shoalrun-example-copy-text",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "shoalrun-example-copy-text",
+      "dependencies": {
+        "react": "19.3.1",
+        "react-dom": "19.3.1"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.3.1",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.3.1.tgz",
+      "integrity": "sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "19.3.1",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.3.1.tgz",
+      "integrity": "sha512-Y0bARz53lhEC1NMCASs0/j+faB/zqt3R8hpvg1e8+61ZVJ4UL0UdC4cBbXfZMcIuhrfgeILTLe+ZeBCavQPtKQ==",
+      "license": "MIT",
+      "dependencies": {
+        "scheduler": "^0.28.0"
+      },
+      "peerDependencies": {
+        "react": "^19.3.1"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz",
+      "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==",
+      "license": "MIT"
+    }
+  }
+}

package/examples/components/copy-text/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "shoalrun-example-copy-text",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  }
+}

package/examples/components/copy-text/plugin.mjs

@@ -0,0 +1,5 @@
+import { defineComponent } from '@shoalrun/cli/components';
+export default defineComponent({
+  children: 'required',
+  content({ children }) { return children; }
+});

package/examples/components/retry-budget/LICENSE.react-dom.txt

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

package/examples/components/retry-budget/LICENSE.react.txt

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

package/examples/components/retry-budget/LICENSE.scheduler.txt

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

package/examples/components/retry-budget/browser.jsx

@@ -0,0 +1,50 @@
+import React, { useEffect, useId, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { retrySchedule } from './model.js';
+
+function RetryCalculator({ policy }) {
+  const id = useId();
+  const [attempts, setAttempts] = useState(String(policy.attempts));
+  const [base, setBase] = useState(String(policy.baseDelayMs));
+  const [cap, setCap] = useState(String(policy.maxDelayMs));
+  const [backoff, setBackoff] = useState(policy.backoff);
+  const [jitter, setJitter] = useState(policy.jitter);
+  const a = Number(attempts), b = Number(base), c = Number(cap);
+  let schedule = [];
+  let valid = true;
+  try { schedule = retrySchedule({ ...policy, attempts: a, baseDelayMs: b, maxDelayMs: c, backoff, jitter }); }
+  catch { valid = false; }
+  const total = schedule.at(-1)?.total ?? 0;
+  const time = value => jitter === 'full' && value ? `0–${value.toLocaleString('en-US')} ms` : `${value.toLocaleString('en-US')} ms`;
+  const number = (name, label, value, onChange, min, max) => <label htmlFor={`${id}-${name}`}>{label}<input id={`${id}-${name}`} type="number" min={min} max={max} step="1" value={value} onChange={event => onChange(event.target.value)} aria-describedby={valid ? undefined : `${id}-error`} /></label>;
+  return <div className="retry-calculator">
+    <div className="retry-calculator-heading"><span className="retry-eyebrow">Interactive example · React</span><h3>Explore a retry budget</h3><p>Change the policy to see how long a client might wait before giving up.</p></div>
+    <fieldset><legend>Retry policy</legend><div className="retry-fields">
+      {number('attempts', 'Maximum attempts', attempts, setAttempts, 1, 8)}
+      {number('base', 'Base delay (ms)', base, setBase, 1, 60000)}
+      {number('cap', 'Delay cap (ms)', cap, setCap, Number(base) || 1, 60000)}
+      <label htmlFor={`${id}-backoff`}>Backoff<select id={`${id}-backoff`} value={backoff} onChange={event => setBackoff(event.target.value)}><option value="constant">Constant</option><option value="exponential">Exponential</option></select></label>
+      <label htmlFor={`${id}-jitter`}>Jitter<select id={`${id}-jitter`} value={jitter} onChange={event => setJitter(event.target.value)}><option value="none">None</option><option value="full">Full jitter</option></select></label>
+    </div></fieldset>
+    {!valid ? <p id={`${id}-error`} role="alert">Use 1–8 attempts and whole-millisecond delays from 1 to 60000. The cap must be at least the base delay.</p> : <>
+      <p className="retry-result" role="status" aria-live="polite"><strong>{time(total)}</strong><span>Total wait budget, excluding request duration and Retry-After.</span></p>
+      <ol className="retry-timeline" aria-label="Attempt timeline">{schedule.map(item => <li key={item.attempt}><span>Attempt {item.attempt}</span><span className="retry-track" aria-hidden="true"><span style={{ width: `${Math.max(2, item.delay / Math.max(...schedule.map(row => row.delay), 1) * 100)}%` }} /></span><strong>{time(item.delay)}</strong></li>)}</ol>
+      {jitter === 'full' && <p>Full jitter chooses a random wait within each range. Expected total wait: {(total / 2).toLocaleString('en-US')} ms.</p>}
+    </>}
+    <p className="retry-note">Safety rules, the configured policy, formulas, code, and a worked schedule remain below in both HTML and Markdown.</p>
+    <button type="button" onClick={() => { setAttempts(String(policy.attempts)); setBase(String(policy.baseDelayMs)); setCap(String(policy.maxDelayMs)); setBackoff(policy.backoff); setJitter(policy.jitter); }}>Reset to configured policy</button>
+  </div>;
+}
+
+export function enhance({ root, controls, data: policy }) {
+  if (root.dataset.shoalrunComponent !== 'RetryBudget') return;
+  return new Promise((resolve, reject) => {
+    const app = createRoot(controls, { onUncaughtError: error => { controls.hidden = true; reject(error); } });
+    function MountedCalculator() {
+      useEffect(() => { controls.hidden = false; resolve(); }, []);
+      return <RetryCalculator policy={policy} />;
+    }
+    // React owns only the initially empty controls slot.
+    app.render(<MountedCalculator />);
+  });
+}

package/examples/components/retry-budget/components.json

@@ -0,0 +1,6 @@
+{
+  "apiVersion": 1,
+  "components": {
+    "RetryBudget": { "module": "./plugin.mjs", "browser": "./browser.jsx", "styles": ["./style.css"] }
+  }
+}

package/examples/components/retry-budget/model.js

@@ -0,0 +1,22 @@
+// Shared by build-time documentation and browser behavior. No DOM dependencies.
+export function validatePolicy(policy) {
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) throw new Error('policy must be an object');
+  const { attempts, baseDelayMs, maxDelayMs, backoff, jitter, retryableStatuses, warning } = policy;
+  if (Object.keys(policy).some(key => !['attempts', 'baseDelayMs', 'maxDelayMs', 'backoff', 'jitter', 'retryableStatuses', 'warning'].includes(key))) throw new Error('policy has an unknown field');
+  if (!Number.isInteger(attempts) || attempts < 1 || attempts > 8) throw new Error('attempts must be an integer from 1 to 8, including the first attempt');
+  if (!Number.isInteger(baseDelayMs) || baseDelayMs < 1 || baseDelayMs > 60000) throw new Error('baseDelayMs must be an integer from 1 to 60000');
+  if (!Number.isInteger(maxDelayMs) || maxDelayMs < baseDelayMs || maxDelayMs > 60000) throw new Error('maxDelayMs must be between baseDelayMs and 60000');
+  if (!['constant', 'exponential'].includes(backoff) || !['none', 'full'].includes(jitter)) throw new Error('backoff must be constant or exponential; jitter must be none or full');
+  if (!Array.isArray(retryableStatuses) || !retryableStatuses.length || new Set(retryableStatuses).size !== retryableStatuses.length || retryableStatuses.some(status => !Number.isInteger(status) || status < 400 || status > 599)) throw new Error('retryableStatuses needs distinct HTTP error status codes');
+  if (typeof warning !== 'string' || !warning.trim()) throw new Error('policy needs a nonempty warning');
+  return policy;
+}
+export function retrySchedule(policy) {
+  validatePolicy(policy);
+  let total = 0;
+  return Array.from({ length: policy.attempts }, (_, index) => {
+    const delay = index === 0 ? 0 : Math.min(policy.maxDelayMs, policy.baseDelayMs * (policy.backoff === 'constant' ? 1 : 2 ** (index - 1)));
+    total += delay;
+    return { attempt: index + 1, delay, total };
+  });
+}

package/examples/components/retry-budget/package-lock.json

@@ -0,0 +1,41 @@
+{
+  "name": "shoalrun-example-retry-budget",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "shoalrun-example-retry-budget",
+      "dependencies": {
+        "react": "19.3.1",
+        "react-dom": "19.3.1"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.3.1",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.3.1.tgz",
+      "integrity": "sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "19.3.1",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.3.1.tgz",
+      "integrity": "sha512-Y0bARz53lhEC1NMCASs0/j+faB/zqt3R8hpvg1e8+61ZVJ4UL0UdC4cBbXfZMcIuhrfgeILTLe+ZeBCavQPtKQ==",
+      "license": "MIT",
+      "dependencies": {
+        "scheduler": "^0.28.0"
+      },
+      "peerDependencies": {
+        "react": "^19.3.1"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz",
+      "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==",
+      "license": "MIT"
+    }
+  }
+}

package/examples/components/retry-budget/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "shoalrun-example-retry-budget",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  }
+}

package/examples/components/retry-budget/plugin.mjs

@@ -0,0 +1,31 @@
+import { defineComponent, content as c } from '@shoalrun/cli/components';
+import policy from './policy.json' with { type: 'json' };
+import { validatePolicy, retrySchedule } from './model.js';
+
+export default defineComponent({
+  attributes: { title: { type: 'string', default: 'Retry budget' } },
+  content({ attributes }) {
+    if (!attributes.title.trim()) throw new Error('title must be nonempty');
+    const model = validatePolicy(policy);
+    const time = value => model.jitter === 'full' && value ? `0–${value} ms` : `${value} ms`;
+    return {
+      data: model,
+      content: [
+        c.paragraph(c.strong(attributes.title)),
+        c.component('Callout', { type: 'warning', label: 'Before you retry' }, [c.paragraph(model.warning)]),
+        c.paragraph('Configured policy. Attempts include the first request; only subsequent attempts wait. These are fictional example settings, not a Shoalrun service limit.'),
+        c.table(['Setting', 'Value'], [
+          ['Maximum attempts', String(model.attempts)], ['Base delay (ms)', String(model.baseDelayMs)], ['Delay cap (ms)', String(model.maxDelayMs)],
+          ['Backoff', model.backoff], ['Jitter', model.jitter], ['Retryable HTTP statuses', model.retryableStatuses.join(', ')]
+        ]),
+        c.paragraph('Supported controls: 1–8 attempts, base delay from 1 to 60000 ms, and a delay cap from the base delay to 60000 ms. Backoff is constant or exponential. Jitter is none or full.'),
+        c.paragraph('For retry number r starting at 1: constant delay = min(cap, base); exponential delay = min(cap, base × 2^(r − 1)). No jitter waits that delay. Full jitter samples uniformly from zero to that delay; its expected wait is half the delay. The calculator shows bounds, not a random prediction.'),
+        c.paragraph('The configured schedule follows. Cumulative wait excludes request duration and any longer Retry-After wait.'),
+        c.table(['Attempt', 'Wait before attempt', 'Cumulative wait'], retrySchedule(model).map(row => [String(row.attempt), time(row.delay), time(row.total)])),
+        c.paragraph('This JavaScript calculates the delay bounds; your request handler must separately enforce retryable statuses, idempotency, and Retry-After.'),
+        c.code(`function retryDelayBounds(retry, policy) {\n  const ceiling = Math.min(policy.maxDelayMs, policy.baseDelayMs *\n    (policy.backoff === 'constant' ? 1 : 2 ** (retry - 1)));\n  return policy.jitter === 'full' ? [0, ceiling] : [ceiling, ceiling];\n}`, 'js'),
+        c.paragraph(c.link('Read the Retry-After HTTP specification', 'https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after'))
+      ]
+    };
+  }
+});

package/examples/components/retry-budget/policy.json

@@ -0,0 +1,9 @@
+{
+  "attempts": 4,
+  "baseDelayMs": 500,
+  "maxDelayMs": 30000,
+  "backoff": "exponential",
+  "jitter": "none",
+  "retryableStatuses": [429, 502, 503, 504],
+  "warning": "Retry only idempotent operations, or requests protected by an idempotency key. Honor a server's Retry-After header; it can require a longer wait than this policy."
+}

package/examples/components/retry-budget/style.css

@@ -0,0 +1,25 @@
+[data-shoalrun-component="RetryBudget"] .retry-calculator {
+  padding: clamp(1rem, 3vw, 1.7rem); margin: 1rem 0 1.5rem;
+  border: 1px solid var(--line, #9998); border-radius: 1rem;
+  background: var(--surface, Canvas); color: var(--text, CanvasText);
+}
+.retry-calculator .retry-eyebrow { font-size: .75rem; letter-spacing: .06em; text-transform: uppercase; opacity: .75; }
+.retry-calculator h3 { margin: .4rem 0; }
+.retry-calculator fieldset { min-width: 0; border: 0; padding: 0; margin: 1.2rem 0; }
+.retry-calculator legend { font-weight: 650; margin-bottom: .65rem; }
+.retry-calculator .retry-fields { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 140px), 1fr)); gap: .85rem; }
+.retry-calculator label { display: grid; gap: .35rem; font-size: .85rem; }
+.retry-calculator input, .retry-calculator select, .retry-calculator button {
+  font: inherit; color: inherit; border: 1px solid var(--line, #9998); border-radius: .4rem; background: var(--surface, Canvas); padding: .55rem .65rem; min-width: 0; width: 100%;
+}
+.retry-calculator input:focus-visible, .retry-calculator select:focus-visible, .retry-calculator button:focus-visible { outline: 2px solid var(--accent, Highlight); outline-offset: 3px; }
+.retry-calculator .retry-result { display: grid; gap: .35rem; padding: 1rem; border-radius: .6rem; background: color-mix(in srgb, var(--accent, #227565) 10%, transparent); }
+.retry-calculator .retry-result strong { font-size: 1.8rem; line-height: 1.2; font-variant-numeric: tabular-nums; }
+.retry-calculator .retry-result span, .retry-calculator .retry-note { font-size: .85rem; }
+.retry-calculator .retry-timeline { list-style: none; padding: 0; margin: 1rem 0; }
+.retry-calculator .retry-timeline li { display: grid; grid-template-columns: 5rem minmax(1rem, 1fr) 7rem; align-items: center; gap: .7rem; margin: .65rem 0; font-size: .85rem; }
+.retry-calculator .retry-timeline strong { text-align: right; font-variant-numeric: tabular-nums; }
+.retry-calculator .retry-track { background: color-mix(in srgb, currentColor 7%, transparent); height: .65rem; border-radius: 1rem; }
+.retry-calculator .retry-track > span { display: block; height: 100%; border-radius: inherit; background: var(--accent, #227565); }
+.retry-calculator button { width: auto; cursor: pointer; }
+@media (max-width: 420px) { .retry-calculator .retry-timeline li { grid-template-columns: 4rem minmax(1rem, 1fr) 6rem; gap: .4rem; font-size: .75rem; } }

package/examples/diagrams/d2-gallery.json

@@ -0,0 +1,138 @@
+[
+  {
+    "id": "flow",
+    "title": "Connected steps",
+    "summary": "Connect the stages of a documentation build.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: right\nsource: Source files\nbuild: Build documentation\nsite: Published site\nsource -> build: compile\nbuild -> site: publish",
+    "width": 640
+  },
+  {
+    "id": "decision",
+    "title": "Decision flow",
+    "summary": "Show approval and revision paths.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: down\ndraft: Draft guide\nreview: Ready to publish? { shape: diamond }\npublish: Publish guide\nrevise: Revise guide\ndraft -> review\nreview -> publish: yes\nreview -> revise: no\nrevise -> draft",
+    "width": 480
+  },
+  {
+    "id": "connections",
+    "title": "Connection styles",
+    "summary": "Distinguish directed, two-way, and dashed relationships.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: right\nwriter: Writer\nreviewer: Reviewer\narchive: Archive { shape: cylinder }\nwriter <-> reviewer: discuss\nreviewer -> archive: approved copy\nwriter -> archive: reference { style.stroke-dash: 4 }",
+    "width": 640
+  },
+  {
+    "id": "containers",
+    "title": "Nested containers",
+    "summary": "Group a site and its supporting services.",
+    "layout": "elk",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: right\nproject: Documentation project {\n content: Content files\n config: Configuration\n}\nsite: Published site {\n html: HTML pages\n markdown: Markdown pages\n}\nproject.content -> site.html\nproject.content -> site.markdown\nproject.config -> site",
+    "width": 640
+  },
+  {
+    "id": "architecture",
+    "title": "Service architecture",
+    "summary": "Connect readers, a documentation endpoint, and stored content.",
+    "layout": "tala",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\nreader: Reader { shape: person }\nsite: Documentation site\nmcp: MCP endpoint\ncontent: Published content { shape: cylinder }\nreader -> site: browse\nreader -> mcp: read with tools\nsite -> content\nmcp -> content",
+    "width": 640
+  },
+  {
+    "id": "tables",
+    "title": "SQL tables",
+    "summary": "Show columns, key constraints, and a foreign-key relationship.",
+    "layout": "elk",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: right\npages: Pages {\n shape: sql_table\n id: text { constraint: primary_key }\n title: text\n}\nsections: Sections {\n shape: sql_table\n id: text { constraint: primary_key }\n page_id: text { constraint: foreign_key }\n heading: text\n}\nsections.page_id -> pages.id",
+    "width": 500
+  },
+  {
+    "id": "uml",
+    "title": "UML classes",
+    "summary": "Describe a page class and its section class.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: right\nPage: {\n shape: class\n title: string\n slug: string\n render(): HTML\n}\nSection: {\n shape: class\n heading: string\n text: string\n}\nPage -> Section: contains",
+    "width": 640
+  },
+  {
+    "id": "sequence",
+    "title": "Sequence diagram",
+    "summary": "Read requests and responses in their declared order.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\nshape: sequence_diagram\nagent: Agent\nserver: MCP server\nindex: Published index\nagent -> server: Search documentation\nserver -> index: Find matching pages\nindex -> server: Page IDs\nserver -> agent: Read instruction\nagent -> server: Read selected page\nserver -> agent: Markdown and citation",
+    "width": 540
+  },
+  {
+    "id": "grid",
+    "title": "Grid layout",
+    "summary": "Arrange related topics in a fixed number of columns.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ngrid-columns: 3\nstart: Start\nconfigure: Configure\nauthor: Author\npublish: Publish\nmeasure: Measure\nmaintain: Maintain",
+    "width": 480
+  },
+  {
+    "id": "styling",
+    "title": "Reusable styles",
+    "summary": "Apply a shared style with explicit contrasting text and fill colors.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: right\nclasses: {\n step: {\n  style.fill: \"#e9f3ef\"\n  style.font-color: \"#16332e\"\n  style.stroke: \"#52706a\"\n  style.border-radius: 8\n }\n}\na: Draft { class: step }\nb: Review { class: step }\nc: Publish { class: step }\na -> b -> c",
+    "width": 560
+  },
+  {
+    "id": "code",
+    "title": "Code block",
+    "summary": "Include a short source-code excerpt as a diagram node.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\nexample: |ts\n  const page = { title: \"Getting started\" };\n  console.log(page.title);\n|",
+    "width": 500
+  },
+  {
+    "id": "layout-tala",
+    "title": "TALA layout",
+    "summary": "Compare the same source using TALA.",
+    "layout": "tala",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: right\nsource: Source\nvalidate: Validate\nhtml: HTML\nmarkdown: Markdown\nsource -> validate\nvalidate -> html\nvalidate -> markdown",
+    "width": 600
+  },
+  {
+    "id": "layout-elk",
+    "title": "ELK layout",
+    "summary": "Compare the same source using ELK.",
+    "layout": "elk",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: right\nsource: Source\nvalidate: Validate\nhtml: HTML\nmarkdown: Markdown\nsource -> validate\nvalidate -> html\nvalidate -> markdown",
+    "width": 540
+  },
+  {
+    "id": "layout-dagre",
+    "title": "Dagre layout",
+    "summary": "Compare the same source using DAGRE.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ndirection: right\nsource: Source\nvalidate: Validate\nhtml: HTML\nmarkdown: Markdown\nsource -> validate\nvalidate -> html\nvalidate -> markdown",
+    "width": 600
+  },
+  {
+    "id": "shapes-1",
+    "title": "D2 shapes 1",
+    "summary": "Compare rectangle, square, page, parallelogram, document, cylinder.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ngrid-columns: 3\nnode0: rectangle { shape: rectangle }\nnode1: square { shape: square }\nnode2: page { shape: page }\nnode3: parallelogram { shape: parallelogram }\nnode4: document { shape: document }\nnode5: cylinder { shape: cylinder }",
+    "width": 580
+  },
+  {
+    "id": "shapes-2",
+    "title": "D2 shapes 2",
+    "summary": "Compare queue, package, step, callout, stored_data, person.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ngrid-columns: 3\nnode0: queue { shape: queue }\nnode1: package { shape: package }\nnode2: step { shape: step }\nnode3: callout { shape: callout }\nnode4: stored_data { shape: stored_data }\nnode5: person { shape: person }",
+    "width": 560
+  },
+  {
+    "id": "shapes-3",
+    "title": "D2 shapes 3",
+    "summary": "Compare diamond, oval, circle, hexagon, cloud, text.",
+    "layout": "dagre",
+    "source": "vars: {\n d2-config: {\n  pad: 16\n }\n}\n\ngrid-columns: 3\nnode0: diamond { shape: diamond }\nnode1: oval { shape: oval }\nnode2: circle { shape: circle }\nnode3: hexagon { shape: hexagon }\nnode4: cloud { shape: cloud }\nnode5: text { shape: text }",
+    "width": 540
+  }
+]