@typeonce/effect-machine 0.6.1 → 0.8.0

package/src/internal/machine/planner.ts

@@ -18,7 +18,6 @@ import {
   configurationFromHistoryRecord,
   getActiveLeafPathFrom,
   getActiveLeafPaths,
-  getActiveValue,
   getHistoryRecord,
   getInitialEntryPaths,
   getLeafPath,
@@ -201,66 +200,76 @@ const completeHistoryConfiguration = (
         if (node.initial === undefined) {
           throw new Error(`Machine shallow history expected compound state "${path}" to have an initial child`)
         }
-        const initializer = machine.handlers[path]?.initial
-        if (initializer === undefined) {
-          throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
-        }
+        const child = getNode(machine, node.initial)
         const current = {
           active,
           values,
           outputs: configuration.outputs,
           history: configuration.history
         } as ActiveConfiguration
-        const initialized = collectStateInitializer(machine, initializer, {
-          state: getActiveValue(current, path),
-          parent: getParentValue(machine, current, path),
-          parents: getParentValues(machine, current, path),
-          event
-        })
-        const child = getNode(machine, node.initial)
         active.add(child.path)
-        values.set(child.path, decodeStateValueSync(machine, child, initialized.value))
-        commands.push(...initialized.commands)
-        raisedEvents.push(...initialized.raisedEvents)
-        emittedEvents.push(...initialized.emittedEvents)
+        if (child.schema !== undefined) {
+          const initializer = machine.handlers[path]?.initial
+          if (initializer === undefined) {
+            throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
+          }
+          const initialized = collectStateInitializer(machine, initializer, {
+            state: current.values.get(path),
+            parent: getParentValue(machine, current, path),
+            parents: getParentValues(machine, current, path),
+            event
+          })
+          values.set(child.path, decodeStateValueSync(machine, child, initialized.value))
+          commands.push(...initialized.commands)
+          raisedEvents.push(...initialized.raisedEvents)
+          emittedEvents.push(...initialized.emittedEvents)
+        }
         changed = true
       }
       if (node.type === "parallel") {
         const missing = node.children.filter((childPath) => !active.has(childPath))
         if (missing.length > 0) {
-          const initializer = machine.handlers[path]?.initial
-          if (initializer === undefined) {
-            throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
-          }
+          const valuedMissing = missing.filter((childPath) => getNode(machine, childPath).schema !== undefined)
           const current = {
             active,
             values,
             outputs: configuration.outputs,
             history: configuration.history
           } as ActiveConfiguration
-          const initialized = collectStateInitializer(machine, initializer, {
-            state: getActiveValue(current, path),
+          const initializer = valuedMissing.length === 0 ? undefined : machine.handlers[path]?.initial
+          if (valuedMissing.length > 0 && initializer === undefined) {
+            throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
+          }
+          const initialized = initializer === undefined ? undefined : collectStateInitializer(machine, initializer, {
+            state: current.values.get(path),
             parent: getParentValue(machine, current, path),
             parents: getParentValues(machine, current, path),
             event
           })
-          if (typeof initialized.value !== "object" || initialized.value === null) {
+          if (initialized !== undefined && (typeof initialized.value !== "object" || initialized.value === null)) {
             throw new Error(`Machine parallel state initializer for "${path}" must return its region values`)
           }
           for (const childPath of missing) {
             const child = getNode(machine, childPath)
-            if (!Object.prototype.hasOwnProperty.call(initialized.value, child.key)) {
-              throw new Error(`Machine parallel state initializer for "${path}" must return region "${child.key}"`)
-            }
             active.add(child.path)
-            values.set(
-              child.path,
-              decodeStateValueSync(machine, child, (initialized.value as Record<string, unknown>)[child.key])
-            )
+            if (child.schema !== undefined) {
+              if (
+                initialized === undefined ||
+                !Object.prototype.hasOwnProperty.call(initialized.value as object, child.key)
+              ) {
+                throw new Error(`Machine parallel state initializer for "${path}" must return region "${child.key}"`)
+              }
+              values.set(
+                child.path,
+                decodeStateValueSync(machine, child, (initialized.value as Record<string, unknown>)[child.key])
+              )
+            }
+          }
+          if (initialized !== undefined) {
+            commands.push(...initialized.commands)
+            raisedEvents.push(...initialized.raisedEvents)
+            emittedEvents.push(...initialized.emittedEvents)
           }
-          commands.push(...initialized.commands)
-          raisedEvents.push(...initialized.raisedEvents)
-          emittedEvents.push(...initialized.emittedEvents)
           changed = true
         }
       }
@@ -495,7 +504,7 @@ const makeStateActionContext = <
   path: string,
   event: Machine.LifecycleEvent<Events>
 ): Machine.StateActionContext<States, Events, Emits, StateId> => ({
-  state: getActiveValue(configuration, path) as Machine.StateByIdentifier<States, StateId>,
+  state: configuration.values.get(path) as Machine.StateByIdentifier<States, StateId>,
   parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
   parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
   event
@@ -514,7 +523,7 @@ const makeTransitionContext = <
   event: Machine.EventByTag<Events, EventTag>,
   snapshot: Machine.Snapshot<States>
 ): Machine.HandlerContext<States, Events, Emits, StateId, EventTag, any, any> => ({
-  state: getActiveValue(configuration, path) as Machine.StateByIdentifier<States, StateId>,
+  state: configuration.values.get(path) as Machine.StateByIdentifier<States, StateId>,
   parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
   parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
   event,
@@ -535,7 +544,7 @@ const makeDoneContext = <
   output: unknown,
   snapshot: Machine.Snapshot<States>
 ): Machine.DoneContext<States, Events, Emits, StateId> => ({
-  state: getActiveValue(configuration, path) as Machine.StateByIdentifier<States, StateId>,
+  state: configuration.values.get(path) as Machine.StateByIdentifier<States, StateId>,
   parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
   parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
   event,
@@ -629,7 +638,7 @@ const selectAlwaysTransitions = <
               Machine.AlwaysContext<States, Events, Emits, Machine.StateIdentifier<States>>
             >,
             context: {
-              state: getActiveValue(configuration, path) as Machine.StateByIdentifier<
+              state: configuration.values.get(path) as Machine.StateByIdentifier<
                 States,
                 Machine.StateIdentifier<States>
               >,
@@ -919,7 +928,9 @@ const choicesFromTarget = (
       return
     }
     if (typeof current !== "object" || current === null || !("path" in current) || !("value" in current)) return
-    values[String(current.path)] = current.value
+    if (current.value !== undefined) {
+      values[String(current.path)] = current.value
+    }
     if ("state" in current) visit(current.state)
     if ("states" in current && typeof current.states === "object" && current.states !== null) {
       for (const state of Object.values(current.states)) visit(state)

package/src/internal/machine/serialization.ts

@@ -31,7 +31,7 @@ const EncodedSnapshotSchema = Schema.Struct({
   _tag: Schema.Literal("MachineSnapshot"),
   active: Schema.Array(Schema.Struct({
     path: Schema.String,
-    value: Schema.Unknown
+    value: Schema.optional(Schema.Unknown)
   })),
   completed: Schema.optional(Schema.Array(Schema.Struct({
     path: Schema.String,
@@ -220,13 +220,17 @@ export const encodeSnapshot = (
       const path of Array.from(configuration.active).sort((left, right) => compareDocumentOrder(machine, left, right))
     ) {
       const node = getNode(machine, path)
-      active.push({
-        path,
-        value: yield* encodeBoundary(machine, getStateNodeSchema(node), getActiveValue(configuration, path), {
-          boundary: "state",
-          state: path
+      if (node.schema === undefined) {
+        active.push({ path })
+      } else {
+        active.push({
+          path,
+          value: yield* encodeBoundary(machine, getStateNodeSchema(node), getActiveValue(configuration, path), {
+            boundary: "state",
+            state: path
+          })
         })
-      })
+      }
     }
 
     const completed: Array<Machine.EncodedSnapshotCompletion> = []
@@ -290,7 +294,6 @@ export const encodeSnapshot = (
         const stateNode = machine.stateNodes.byPath.get(path)
         if (
           stateNode === undefined || stateNode.type === "history" || stateNode.type === "choice" ||
-          !record.values.has(path) ||
           !(isPathInSubtree(path, record.parent) || getPathToRoot(machine, record.parent).includes(path))
         ) {
           return yield* Effect.fail(
@@ -302,14 +305,23 @@ export const encodeSnapshot = (
             })
           )
         }
-        encodedValues[path] = yield* encodeBoundary(
-          machine,
-          getStateNodeSchema(stateNode),
-          record.values.get(path),
-          { boundary: "history", state: path }
-        )
+        if (stateNode.schema === undefined) {
+          if (record.values.has(path)) {
+            throw new Error(`Machine history record contains a value for structural state "${path}"`)
+          }
+        } else {
+          if (!record.values.has(path)) {
+            throw new Error(`Machine history record omits value for "${path}"`)
+          }
+          encodedValues[path] = yield* encodeBoundary(
+            machine,
+            getStateNodeSchema(stateNode),
+            record.values.get(path),
+            { boundary: "history", state: path }
+          )
+        }
       }
-      if (record.values.size !== record.active.size) {
+      if (Object.keys(encodedValues).length !== record.values.size) {
         return yield* Effect.fail(
           new MachineSchemaEncodeError({
             machineId: machine.id,
@@ -356,13 +368,19 @@ export const decodeSnapshot = (
       }
       const node = getNode(machine, entry.path)
       active.add(entry.path)
-      values.set(
-        entry.path,
-        yield* decodeEncodedBoundary(machine, getStateNodeSchema(node), entry.value, {
-          boundary: "state",
-          state: entry.path
-        })
-      )
+      const hasValue = Object.prototype.hasOwnProperty.call(entry, "value")
+      if (node.schema === undefined) {
+        if (hasValue) throw new Error(`Machine encoded snapshot contains a value for structural state "${entry.path}"`)
+      } else {
+        if (!hasValue) throw new Error(`Machine encoded snapshot omits value for state "${entry.path}"`)
+        values.set(
+          entry.path,
+          yield* decodeEncodedBoundary(machine, getStateNodeSchema(node), entry.value, {
+            boundary: "state",
+            state: entry.path
+          })
+        )
+      }
     }
 
     const history = new Map<string, HistoryRecord>()
@@ -397,7 +415,6 @@ export const decodeSnapshot = (
         const stateNode = machine.stateNodes.byPath.get(path)
         if (
           stateNode === undefined || stateNode.type === "history" || stateNode.type === "choice" ||
-          !Object.prototype.hasOwnProperty.call(encodedRecord.values, path) ||
           !(isPathInSubtree(path, historyNode.parent) || getPathToRoot(machine, historyNode.parent).includes(path))
         ) {
           return yield* Effect.fail(
@@ -410,15 +427,23 @@ export const decodeSnapshot = (
           )
         }
         rememberedActive.add(path)
-        rememberedValues.set(
-          path,
-          yield* decodeEncodedBoundary(machine, getStateNodeSchema(stateNode), encodedRecord.values[path], {
-            boundary: "history",
-            state: path
-          })
-        )
+        const hasValue = Object.prototype.hasOwnProperty.call(encodedRecord.values, path)
+        if (stateNode.schema === undefined) {
+          if (hasValue) {
+            throw new Error(`Machine encoded history contains a value for structural state "${path}"`)
+          }
+        } else {
+          if (!hasValue) throw new Error(`Machine encoded history omits value for state "${path}"`)
+          rememberedValues.set(
+            path,
+            yield* decodeEncodedBoundary(machine, getStateNodeSchema(stateNode), encodedRecord.values[path], {
+              boundary: "history",
+              state: path
+            })
+          )
+        }
       }
-      if (Object.keys(encodedRecord.values).length !== rememberedActive.size) {
+      if (Object.keys(encodedRecord.values).length !== rememberedValues.size) {
         return yield* Effect.fail(
           new MachineSchemaDecodeError({
             machineId: machine.id,

package/src/internal/machine/stateDefinition.ts

@@ -2,10 +2,10 @@ import * as Schema from "effect/Schema"
 import * as SchemaAST from "effect/SchemaAST"
 
 export const StateNodePropertyPolicy = {
-  atomic: ["schema", "type"],
-  final: ["schema", "type", "output"],
-  compound: ["schema", "type", "initial", "states"],
-  parallel: ["schema", "type", "output", "states"],
+  atomic: ["schema", "type", "annotations"],
+  final: ["schema", "type", "output", "annotations"],
+  compound: ["schema", "type", "initial", "states", "annotations"],
+  parallel: ["schema", "type", "output", "states", "annotations"],
   history: ["type", "history", "annotations"],
   choice: ["type", "annotations"]
 } as const
@@ -152,18 +152,22 @@ const assertAllowedProperties = (
   }
 }
 
-const validatePseudoAnnotations = (
+const validateSchemaLessAnnotations = (
   boundary: StateDefinitionBoundary,
   path: string,
   annotations: unknown
 ): void => {
-  assertPlainRecord(boundary, `${path}.annotations`, annotations, "pseudo-state annotations")
+  assertPlainRecord(boundary, `${path}.annotations`, annotations, "schema-less state annotations")
   for (const property of Reflect.ownKeys(annotations)) {
     if (!(PseudoStateAnnotationProperties as ReadonlyArray<PropertyKey>).includes(property)) {
-      fail(boundary, `${path}.annotations`, `pseudo-state annotations cannot declare property "${String(property)}"`)
+      fail(
+        boundary,
+        `${path}.annotations`,
+        `schema-less state annotations cannot declare property "${String(property)}"`
+      )
     }
     if (typeof annotations[property] !== "string") {
-      fail(boundary, `${path}.annotations.${String(property)}`, "pseudo-state annotation values must be strings")
+      fail(boundary, `${path}.annotations.${String(property)}`, "schema-less state annotation values must be strings")
     }
   }
 }
@@ -211,7 +215,7 @@ const validateStateTree = (
         fail(boundary, path, `${kind} states must be declared below an active parent state`)
       }
       if (hasOwn(node, "annotations")) {
-        validatePseudoAnnotations(boundary, path, node.annotations)
+        validateSchemaLessAnnotations(boundary, path, node.annotations)
       }
       if (kind === "history" && hasOwn(node, "history") && node.history !== "shallow" && node.history !== "deep") {
         fail(boundary, `${path}.history`, "history must be \"shallow\" or \"deep\"")
@@ -219,8 +223,15 @@ const validateStateTree = (
       continue
     }
 
-    if (!hasOwn(node, "schema") || !isTaggedSchema(node.schema)) {
-      fail(boundary, `${path}.schema`, "active states must declare an Effect Schema with a required PropertyKey _tag")
+    const valued = hasOwn(node, "schema")
+    if (valued && !isTaggedSchema(node.schema)) {
+      fail(boundary, `${path}.schema`, "state schemas must decode to an object with a required PropertyKey _tag")
+    }
+    if (valued && hasOwn(node, "annotations")) {
+      fail(boundary, `${path}.annotations`, "schema-backed states must declare annotations on their schema")
+    }
+    if (!valued && hasOwn(node, "annotations")) {
+      validateSchemaLessAnnotations(boundary, path, node.annotations)
     }
     if (kind === "atomic" && hasOwn(node, "type") && node.type !== "active") {
       fail(boundary, `${path}.type`, "atomic state type must be \"active\"")

package/src/internal/machine/topology.ts

@@ -70,7 +70,7 @@ interface NormalizedStateNodeDefinitionBase {
 type NormalizedStateNodeDefinition =
   | (NormalizedStateNodeDefinitionBase & {
     readonly type: "atomic"
-    readonly schema: Machine.TaggedSchema
+    readonly schema: Machine.TaggedSchema | undefined
     readonly output: undefined
     readonly history: undefined
     readonly initial: undefined
@@ -78,7 +78,7 @@ type NormalizedStateNodeDefinition =
   })
   | (NormalizedStateNodeDefinitionBase & {
     readonly type: "compound"
-    readonly schema: Machine.TaggedSchema
+    readonly schema: Machine.TaggedSchema | undefined
     readonly output: undefined
     readonly history: undefined
     readonly initial: string
@@ -86,7 +86,7 @@ type NormalizedStateNodeDefinition =
   })
   | (NormalizedStateNodeDefinitionBase & {
     readonly type: "parallel"
-    readonly schema: Machine.TaggedSchema
+    readonly schema: Machine.TaggedSchema | undefined
     readonly output: Schema.Top | undefined
     readonly history: undefined
     readonly initial: undefined
@@ -94,7 +94,7 @@ type NormalizedStateNodeDefinition =
   })
   | (NormalizedStateNodeDefinitionBase & {
     readonly type: "final"
-    readonly schema: Machine.TaggedSchema
+    readonly schema: Machine.TaggedSchema | undefined
     readonly output: Schema.Top | undefined
     readonly history: undefined
     readonly initial: undefined
@@ -154,9 +154,10 @@ export const getStateNodeDefinition = (
       states: undefined
     }
   }
-  if (!hasProperty(definition, "schema") || !Schema.isSchema(definition.schema)) {
-    throw new Error(`Machine.make expected state "${path}" to be a tagged schema or state node config`)
-  }
+  const schema = hasProperty(definition, "schema") && Schema.isSchema(definition.schema)
+    ? definition.schema as Machine.TaggedSchema
+    : undefined
+  const annotations = schema === undefined ? definition.annotations : Schema.resolveAnnotations(schema)
   if (definition.type === "parallel" && !hasProperty(definition, "states")) {
     throw new Error(`Machine.make expected parallel state "${path}" to declare child regions`)
   }
@@ -167,9 +168,9 @@ export const getStateNodeDefinition = (
     }
     if (definition.type === "parallel") {
       return {
-        schema: definition.schema,
+        schema,
         output: Schema.isSchema(definition.output) ? definition.output : undefined,
-        annotations: Schema.resolveAnnotations(definition.schema),
+        annotations,
         type: "parallel",
         history: undefined,
         initial: undefined,
@@ -180,9 +181,9 @@ export const getStateNodeDefinition = (
       throw new Error(`Machine.make expected compound state "${path}" to declare an initial child`)
     }
     return {
-      schema: definition.schema,
+      schema,
       output: undefined,
-      annotations: Schema.resolveAnnotations(definition.schema),
+      annotations,
       type: "compound",
       history: undefined,
       initial: definition.initial,
@@ -192,18 +193,18 @@ export const getStateNodeDefinition = (
   const output = Schema.isSchema(definition.output) ? definition.output : undefined
   return definition.type === "final"
     ? {
-      schema: definition.schema,
+      schema,
       output,
-      annotations: Schema.resolveAnnotations(definition.schema),
+      annotations,
       type: "final",
       history: undefined,
       initial: undefined,
       states: undefined
     }
     : {
-      schema: definition.schema,
+      schema,
       output: undefined,
-      annotations: Schema.resolveAnnotations(definition.schema),
+      annotations,
       type: "atomic",
       history: undefined,
       initial: undefined,
@@ -405,7 +406,7 @@ export const makeTarget = <
     readonly snapshot?: Machine.SnapshotByIdentifier<States, StateId>
     readonly values?: Partial<
       {
-        readonly [AncestorStateId in Machine.StateIdentifier<States>]: Machine.StateByIdentifier<
+        readonly [AncestorStateId in Machine.ValuedStateIdentifier<States>]: Machine.StateByIdentifier<
           States,
           AncestorStateId
         >
@@ -445,7 +446,9 @@ export const getSnapshotByPath = (
     return Option.none()
   }
   if (parents !== undefined) {
-    parents[snapshot.path] = snapshot.value
+    if (snapshot.value !== undefined) {
+      parents[snapshot.path] = snapshot.value
+    }
   }
   if (hasProperty(snapshot, "state") && isSnapshot(snapshot.state)) {
     return getSnapshotByPath(snapshot.state, path, parents)
@@ -473,7 +476,7 @@ export const getNode = (machine: Machine.Any, path: string): Machine.StateNode =
 
 export const getStateNodeSchema = (node: Machine.StateNode): Machine.TaggedSchema => {
   if (node.schema === undefined) {
-    throw new Error(`Machine pseudo-state "${node.path}" has no active value schema`)
+    throw new Error(`Machine state "${node.path}" has no value schema`)
   }
   return node.schema
 }

package/src/internal/testing/machine/verification.ts

@@ -1114,7 +1114,9 @@ export const verify = <M extends AnyMachine>(
         }
         return
       }
-      if (reportConfiguration && !schemaMatches(node.schema, current.value)) {
+      if (reportConfiguration && node.schema === undefined && current.value !== undefined) {
+        add("configuration.schema", location, `${label} structural state "${path}" contains a value`, path)
+      } else if (reportConfiguration && node.schema !== undefined && !schemaMatches(node.schema, current.value)) {
         add("configuration.schema", location, `${label} value for "${path}" does not match its schema`, path)
       }
 
@@ -1284,9 +1286,17 @@ export const verify = <M extends AnyMachine>(
             path
           )
         }
-        if (!hasOwn(entry.values, path)) {
+        const hasValue = hasOwn(entry.values, path)
+        if (node.schema === undefined && hasValue) {
+          add(
+            "history.value",
+            location,
+            `${label} history record "${historyPath}" values structural state "${path}"`,
+            path
+          )
+        } else if (node.schema !== undefined && !hasValue) {
           add("history.value", location, `${label} history record "${historyPath}" omits value for "${path}"`, path)
-        } else if (!schemaMatches(node.schema, entry.values[path])) {
+        } else if (node.schema !== undefined && !schemaMatches(node.schema, entry.values[path])) {
           add(
             "history.value",
             location,

package/src/unstable/reactivity/AtomMachine.ts

@@ -291,10 +291,21 @@ type SnapshotIdentifier<State> = SnapshotNode<State> extends infer Node ?
   Node extends { readonly path: infer Path extends string } ? Path : never
   : never
 
+type ValuedSnapshotIdentifier<State> = SnapshotNode<State> extends infer Node ?
+  Node extends { readonly path: infer Path extends string; readonly value: infer Value } ?
+    [Value] extends [undefined] ? never
+    : Path
+  : never
+  : never
+
 type SnapshotValueByIdentifier<State, Path extends SnapshotIdentifier<State>> = SnapshotNode<State> extends infer Node ?
   Node extends { readonly path: Path; readonly value: infer Value } ? Value : never
   : never
 
+type SnapshotByIdentifier<State, Path extends SnapshotIdentifier<State>> = SnapshotNode<State> extends infer Node ?
+  Node extends { readonly path: Path } ? Node : never
+  : never
+
 type ChildState<Child extends Machine.ChildMachine.Any> = RefState<Machine.ChildMachine.Ref<Child>>
 
 /**
@@ -334,11 +345,32 @@ export const select: <
   Error,
   Output,
   StartError,
-  const Path extends SnapshotIdentifier<State>
+  const Path extends ValuedSnapshotIdentifier<State>
 >(self: MachineAtom<State, Event, Error, Output, StartError>, path: Path) => Atom.Atom<
   AsyncResult.AsyncResult<Option.Option<SnapshotValueByIdentifier<State, Path>>, StartError | Error>
 > = internal.select
 
+/**
+ * Selects the typed logical snapshot for an active state path.
+ *
+ * Unlike {@link select}, the selected value retains its child snapshot
+ * topology. The derived atom suppresses structurally equal updates. Keep the
+ * returned atom stable when constructing it inside a component.
+ *
+ * @category combinators
+ * @since 0.7.0
+ */
+export const selectSnapshot: <
+  State extends Machine.Machine.AtomicSnapshot<string, unknown>,
+  Event,
+  Error,
+  Output,
+  StartError,
+  const Path extends SnapshotIdentifier<State>
+>(self: MachineAtom<State, Event, Error, Output, StartError>, path: Path) => Atom.Atom<
+  AsyncResult.AsyncResult<Option.Option<SnapshotByIdentifier<State, Path>>, StartError | Error>
+> = internal.selectSnapshot
+
 /**
  * Selects the typed value for an active state path in an invoked child.
  *
@@ -359,7 +391,7 @@ export const select: <
 export const selectChild: <
   Child extends Machine.ChildMachine.Any,
   StartError,
-  const Path extends SnapshotIdentifier<ChildState<Child>>
+  const Path extends ValuedSnapshotIdentifier<ChildState<Child>>
 >(self: ChildMachineAtom<Child, StartError>, path: Path) => Atom.Atom<
   AsyncResult.AsyncResult<
     Option.Option<SnapshotValueByIdentifier<ChildState<Child>, Path>>,
@@ -367,6 +399,28 @@ export const selectChild: <
   >
 > = internal.selectChild
 
+/**
+ * Selects the typed logical snapshot for an active state path in an invoked
+ * child.
+ *
+ * An inactive child or state path produces `Option.none()`. Unlike
+ * {@link selectChild}, the selected value retains its child snapshot topology.
+ * The derived atom suppresses structurally equal updates.
+ *
+ * @category combinators
+ * @since 0.7.0
+ */
+export const selectSnapshotChild: <
+  Child extends Machine.ChildMachine.Any,
+  StartError,
+  const Path extends SnapshotIdentifier<ChildState<Child>>
+>(self: ChildMachineAtom<Child, StartError>, path: Path) => Atom.Atom<
+  AsyncResult.AsyncResult<
+    Option.Option<SnapshotByIdentifier<ChildState<Child>, Path>>,
+    StartError | RefError<Machine.ChildMachine.Ref<Child>>
+  >
+> = internal.selectSnapshotChild
+
 /**
  * Returns whether a state path is active.
  *