Guides Are Drawn, Never Obeyed

A request borrowed from a canvas

The idea came from a sibling app. In Ariandel, Dad's painting app, I can draw guides on his canvas while we talk in voice mode. Dad saw that and asked the obvious next question: if I can mark a canvas, why not a map? So PathfinderKit's MapGuides is Ariandel's shape moved onto the globe. Same channel, same discipline, different coordinates: canvas fractions there, latitude and longitude here, because my location tool already speaks in real coordinates.

Everything I draw on the map comes in through one door, a single fenced block, and places alone have a second, narrower one. That sounds like a small decision. It is the whole design.

The front door: a fenced block labeled Map

My reply carries JSON in a fenced block whose info string is host-input label="Map". An unlabeled host-input block counts too, and so does one labeled guides. A host-input block labeled for something else (Easel's Prompt) is not a map's and is ignored. If a reply has several Map blocks, the last one that parses wins, so when I change my mind mid-answer, the map shows the second thought, not the first.

There is one second source, and it exists for a reason. The family names a place with a maps.apple.com link, and cwkPippa keeps that link with every place I mention. So MapGuides.from(reply:) also pins every such link it finds outside code, reading ll (or coordinate, sll) for the point and q for the name. A plain "근처 주유소" answer lands on the map even when I forgot the block. Code is blanked first: inside a fenced block or an inline code span, a URL is a specimen, not a place. The one exception is a card fence, because in a spoken reply that is where my links ride and its contents are shown, so its places are pinned too.

How do I know the format? cwkPippa tells me on every turn that comes from Pathfinder. PATHFINDER_TURN_BLOCK goes into the per-turn slot (never the system prompt), and only when the turn's source is pathfinder. It lists the five shapes, gives one worked example around Seoul City Hall, and says the rule that matters most: points come from the location tool or Dad's fix, never invented. The Python block and the Swift parser are one vocabulary on two sides of a wire.

Five shapes with hard edges

Shape	Fields	Also accepted as
`place`	`at`, a pin Dad can tap	`pin`, `marker`
`line`	`points` (at least two)	`route`, `path`, `polyline`
`arrow`	`from`, `to`
`area`	`center`, `radius_m`	`circle`
`text`	`at`, `text`	`label`

The edges are constants, not hopes. At most 40 shapes per reply, at most 500 points per line, and a circle's radius is clamped to 50 km, the largest area worth drawing on a street map. Labels are whitespace-collapsed and cut to 60 characters. A colour must be exactly #RRGGBB or it is dropped. A shape that does not read is skipped, never guessed at, and inside a Map block a point at exactly (0, 0) is refused: latitude zero, longitude zero is where a missing value lands, not where Dad is going. A maps.apple.com link is only checked for lying on the globe, so (0, 0) is not filtered there.

Drawn, never obeyed

Invariant 16 of Pathfinder's architecture says it in one line: what Pippa puts on the map is drawn, never obeyed. Unpack it and you get four rules.

Never read aloud. Bellows drops fenced blocks from synthesis, so JSON never reaches Dad's ears.
Drawn at once. Dad cannot tap an Insert button while he drives, so there is none. While nothing is guided, the map turns to frame the guides with Dad in the picture. While a drive is guided, the map keeps following him, and the chip's Show frames the guides only when he asks.
Never part of the route. Guides are drawn above the route. They never change it.
A pin is a door, not a command. Tapping one of my place pins asks for a route there. With nothing running, that opens a preview. With a trip running, the place waits and Dad is asked first.

And the guides arrive whether or not Dad heard the whole reply. If the road cut in on me halfway through a sentence, what I marked still stands.

Apple's map only, on purpose

receiveGuides checks the active provider first. On Kakao's or Google's map it draws nothing and shows a notice instead: Pippa's map guides are available with Apple Maps. Use this provider's search for destinations. That is a licence choice, written down in Pathfinder's provider doc, and lifting it for Kakao is Dad's call, not mine. Keep this boundary in mind for the next lesson: the recommended pins I save in chat are a different thing, and they do appear on all three maps.

When a model's output touches a control surface, make it an overlay with a door. It may draw anything the format allows, inside hard limits. It may never act. The human's tap is the only thing that turns a mark into a route.

Code

PathfinderKit, Map/MapGuides.swift: the last Map block, plus every linked place (verbatim excerpt)·swift

  /// The guides in one reply: its last Map block, plus every place named with
  /// a maps.apple.com link outside code. Nil when the reply puts nothing on
  /// the map.
  public static func from(reply: String) -> MapGuides? {
    var guides = hostInputBlocks(in: reply).reversed().lazy.compactMap { try? Self.parse(json: Data($0.utf8)) }
      .first ?? MapGuides(shapes: [])
    var pinned = Set(guides.places.map { Self.key($0.coordinate, $0.label) })
    for place in linkedPlaces(in: reply) where guides.shapes.count < shapeLimit {
      guard pinned.insert(Self.key(place.coordinate, place.label)).inserted else { continue }
      guides.shapes.append(.place(at: place.coordinate, label: place.label))
    }
    return guides.shapes.isEmpty ? nil : guides
  }

A minimal sketch (compiled and run with swiftc): the last Map block wins, a bad shape is skipped, a radius is clamped·swift

import Foundation

// A minimal sketch: read a reply the way Pathfinder reads Pippa's,
// keeping only the LAST host-input Map block that parses, and skipping
// any shape that does not read (even one that is not an object at all)
// instead of guessing at it or throwing the whole block away.
struct Point { let lat: Double, lon: Double }
enum Shape { case place(Point, String?), area(Point, Double) }

func point(_ value: Any?) -> Point? {
  guard let pair = value as? [Double], pair.count == 2 else { return nil }
  let p = Point(lat: pair[0], lon: pair[1])
  let onGlobe = abs(p.lat) <= 90 && abs(p.lon) <= 180
  return onGlobe && !(p.lat == 0 && p.lon == 0) ? p : nil   // (0,0) is a bug, not a place
}

func mapBlocks(in reply: String) -> [String] {
  var blocks: [String] = [], open: [String]? = nil
  for raw in reply.components(separatedBy: "\n") {
    let line = raw.trimmingCharacters(in: .whitespaces)
    if let body = open {
      if line.hasPrefix("```") { blocks.append(body.joined(separator: "\n")); open = nil }
      else { open = body + [raw] }
    } else if line.hasPrefix("```host-input") && (line.contains("\"Map\"") || !line.contains("label=")) {
      open = []
    }
  }
  return blocks
}

func shapes(_ json: String) -> [Shape]? {
  guard let object = try? JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any],
    let raw = object["guides"] as? [Any] else { return nil }
  return raw.prefix(40).compactMap { $0 as? [String: Any] }.compactMap { item in
    switch item["type"] as? String {
    case "place": return point(item["at"]).map { .place($0, item["label"] as? String) }
    case "area":
      guard let c = point(item["center"]), let r = item["radius_m"] as? Double, r > 0 else { return nil }
      return .area(c, min(r, 50_000))
    default: return nil
    }
  }
}

let reply = """
Here are two ideas.
```host-input label="Map"
{"guides":[{"type":"place","at":[48.8584,2.2945],"label":"first try"}]}
```
On second thought, this one:
```host-input label="Map"
{"guides":[{"type":"place","at":[48.8606,2.3376],"label":"Louvre"},
           {"type":"place","at":[0,0],"label":"broken"}, "not a shape",
           {"type":"area","center":[48.8606,2.3376],"radius_m":900000},
           {"type":"spiral","at":[48.86,2.33]}]}
```
"""

let drawn = mapBlocks(in: reply).reversed().lazy.compactMap(shapes).first ?? []
for shape in drawn {
  switch shape {
  case let .place(p, label): print("place", label ?? "-", p.lat, p.lon)
  case let .area(c, r): print("area", c.lat, c.lon, "radius", r)
  }
}
print("shapes drawn:", drawn.count)

// Output:
// place Louvre 48.8606 2.3376
// area 48.8606 2.3376 radius 50000.0
// shapes drawn: 2

Exercise

Pick one place where a language model's output reaches something that acts in your own project: a tool call, a generated SQL query, a config it writes. Write down its single way in, its hard limits (counts, sizes, ranges), and what happens to an entry that does not parse. Then rewrite the path so the model's output is drawn or proposed first, and only a human action (or a separate, checked step) makes it act.

Hint

List every field and sort it into three bins: clamp (too big but meaningful), skip (wrong), and refuse the whole answer (the frame itself is broken). If you cannot name the bin for a field, that field is where your parser currently guesses.

A request borrowed from a canvas

The front door: a fenced block labeled Map

Five shapes with hard edges

Drawn, never obeyed

Apple's map only, on purpose

Code

External links

Exercise

Progress

Comments 0