feat(spf): HLS engine composition walkthrough + doc-driven cleanups (#1512)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

packages/utils/src/string/generate-id.ts

@@ -0,0 +1,11 @@
+/**
+ * Generate a unique-ish string ID via timestamp + random.
+ *
+ * @returns String in `timestamp-random` format (e.g. `"1738423156789-542891"`).
+ *
+ * @example
+ * const id = generateId(); // "1738423156789-542891"
+ */
+export function generateId(): string {
+  return `${Date.now()}-${Math.floor(Math.random() * 1000000)}`;
+}

packages/utils/src/string/index.ts

@@ -1 +1,2 @@
 export * from './casing';
+export * from './generate-id';

packages/utils/src/string/tests/generate-id.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { generateId } from '../generate-id';
+
+describe('generateId', () => {
+  it('generates a string ID', () => {
+    const id = generateId();
+
+    expect(typeof id).toBe('string');
+  });
+
+  it('generates unique IDs', () => {
+    const id1 = generateId();
+    const id2 = generateId();
+    const id3 = generateId();
+
+    expect(id1).not.toBe(id2);
+    expect(id2).not.toBe(id3);
+    expect(id1).not.toBe(id3);
+  });
+
+  it('generates IDs without decimals', () => {
+    const id = generateId();
+
+    expect(id).not.toMatch(/\./);
+  });
+
+  it('generates IDs in consistent format', () => {
+    const id = generateId();
+
+    // Should be timestamp-random format
+    expect(id).toMatch(/^\d+-\d+$/);
+  });
+
+  it('generates different IDs in rapid succession', () => {
+    const ids = new Set<string>();
+
+    for (let i = 0; i < 100; i++) {
+      ids.add(generateId());
+    }
+
+    // All should be unique
+    expect(ids.size).toBe(100);
+  });
+});